Restructure CLI as gh-app with subcommands

Replace individual binaries with a single `gh-app` entry point
supporting: token, pull, clone, check-token, list-repos.
Adds shared auth helper and --help flag on all commands.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: randyquaye

README.md

@@ -1,6 +1,6 @@
-# github-app-util
+# gh-app
 
-Generate GitHub App installation tokens for API access.
+A CLI for GitHub App authentication and git operations.
 
 ## Prerequisites
 
@@ -20,7 +20,7 @@ Or clone and install locally:
 ```bash
 git clone https://github.com/AztecProtocol/github-app-util.git
 cd github-app-util
-npm install
+npm install && npm link
 ```
 
 ## Setup
@@ -43,40 +43,53 @@ GITHUB_PRIVATE_KEY_PATH=./private-key.pem
 
 ## Usage
 
-If installed globally:
+```
+gh-app <command> [options]
+
+Commands:
+  token          Generate an installation token
+  pull           Pull a repo using a fresh token
+  clone          Clone a repo using a fresh token
+  check-token    Show token validity and expiry
+  list-repos     List accessible repositories
+```
+
+Run `gh-app <command> --help` for command-specific help.
+
+### Generate a token
 
 ```bash
-github-app-util
+gh-app token
 ```
 
-If cloned locally:
+To capture as an environment variable:
 
 ```bash
-node bin/get-token.js
+export GITHUB_TOKEN=$(gh-app token 2>/dev/null)
 ```
 
-The tool outputs an installation token you can use for API calls.
-
-To capture the token as an environment variable:
+### Pull a repo
 
 ```bash
-export GITHUB_TOKEN=$(github-app-util 2>/dev/null)
+gh-app pull owner/repo
+gh-app pull owner/repo feature-branch
 ```
 
-The `2>/dev/null` suppresses the TTY warning so only the token is captured.
-
-Then you can use the git api normally with the token:
+### Clone a repo
 
 ```bash
-  git pull https://<GITHUB_TOKEN>@github.com/OWNER/REPO.git main                    
+gh-app clone owner/repo
+gh-app clone owner/repo my-directory
 ```
 
-Or set it more persistently:                                                      
-```bash                                                                                    
-  # Set the remote URL with the token
-  git remote set-url origin https://<GITHUB_TOKEN>@github.com/OWNER/REPO.git        
-   
-  # Then pull normally                                                              
-  git pull
+### Check token validity
+
+```bash
+gh-app check-token
 ```
 
+### List accessible repos
+
+```bash
+gh-app list-repos
+```

bin/commands/check-token.js

@@ -0,0 +1,29 @@
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+  console.log(`Usage: gh-app check-token
+
+Show the current installation token's validity and expiry time.
+
+Options:
+  -h, --help    Show this help message`);
+  process.exit(0);
+}
+
+import { getInstallationAuth } from "../lib/auth.js";
+
+const { octokit, token, expiresAt } = await getInstallationAuth();
+
+const { data: app } = await octokit.rest.apps.getAuthenticated();
+console.log(`App:            ${app.name}`);
+
+const expires = new Date(expiresAt);
+const now = new Date();
+const minutesLeft = Math.round((expires - now) / 60000);
+
+console.log(`Token prefix:   ${token.slice(0, 8)}...`);
+console.log(`Expires at:     ${expires.toISOString()}`);
+
+if (minutesLeft > 0) {
+  console.log(`Status:         valid (${minutesLeft} min remaining)`);
+} else {
+  console.log(`Status:         expired`);
+}

bin/commands/clone.js

@@ -0,0 +1,35 @@
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+  console.log(`Usage: gh-app clone <owner/repo> [directory]
+
+Clone a repo using a fresh GitHub App installation token.
+
+Options:
+  -h, --help    Show this help message
+
+Examples:
+  gh-app clone myorg/myrepo
+  gh-app clone myorg/myrepo ./my-directory`);
+  process.exit(0);
+}
+
+import { execSync } from "child_process";
+import { getInstallationAuth } from "../lib/auth.js";
+
+const [repoSlug, directory] = process.argv.slice(2);
+
+if (!repoSlug) {
+  console.error("Usage: gh-app clone <owner/repo> [directory]");
+  console.error("Run gh-app clone --help for more information.");
+  process.exit(1);
+}
+
+const { token } = await getInstallationAuth();
+const remote = `https://x-access-token:${token}@github.com/${repoSlug}.git`;
+
+const cmd = directory ? `git clone ${remote} ${directory}` : `git clone ${remote}`;
+
+try {
+  execSync(cmd, { stdio: "inherit" });
+} catch {
+  process.exit(1);
+}

bin/commands/list-repos.js

@@ -0,0 +1,29 @@
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+  console.log(`Usage: gh-app list-repos
+
+List all repositories accessible to the GitHub App installation.
+
+Options:
+  -h, --help    Show this help message`);
+  process.exit(0);
+}
+
+import { getInstallationAuth } from "../lib/auth.js";
+
+const { octokit } = await getInstallationAuth();
+
+const repos = await octokit.paginate(
+  octokit.rest.apps.listReposAccessibleToInstallation,
+  { per_page: 100 }
+);
+
+if (repos.length === 0) {
+  console.log("No repositories accessible to this installation.");
+  process.exit(0);
+}
+
+console.log(`Accessible repositories (${repos.length}):\n`);
+for (const repo of repos) {
+  const visibility = repo.private ? "private" : "public";
+  console.log(`  ${repo.full_name}  (${visibility})`);
+}

bin/commands/pull.js

@@ -0,0 +1,36 @@
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+  console.log(`Usage: gh-app pull <owner/repo> [branch]
+
+Pull latest changes using a fresh GitHub App installation token.
+If a branch is specified, only that branch is pulled.
+
+Options:
+  -h, --help    Show this help message
+
+Examples:
+  gh-app pull myorg/myrepo
+  gh-app pull myorg/myrepo feature-branch`);
+  process.exit(0);
+}
+
+import { execSync } from "child_process";
+import { getInstallationAuth } from "../lib/auth.js";
+
+const [repoSlug, branch] = process.argv.slice(2);
+
+if (!repoSlug) {
+  console.error("Usage: gh-app pull <owner/repo> [branch]");
+  console.error("Run gh-app pull --help for more information.");
+  process.exit(1);
+}
+
+const { token } = await getInstallationAuth();
+const remote = `https://x-access-token:${token}@github.com/${repoSlug}.git`;
+
+const cmd = branch ? `git pull ${remote} ${branch}` : `git pull ${remote}`;
+
+try {
+  execSync(cmd, { stdio: "inherit" });
+} catch {
+  process.exit(1);
+}

bin/commands/token.js

@@ -0,0 +1,28 @@
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+  console.log(`Usage: gh-app token
+
+Generate a GitHub App installation token.
+
+Options:
+  -h, --help    Show this help message
+
+Environment variables:
+  GITHUB_APP_ID              GitHub App ID (required)
+  GITHUB_INSTALLATION_ID     Installation ID (required)
+  GITHUB_PRIVATE_KEY_PATH    Path to private key (default: ./private-key.pem)`);
+  process.exit(0);
+}
+
+import { getInstallationAuth } from "../lib/auth.js";
+
+const { token } = await getInstallationAuth();
+
+if (!token) {
+  console.error("Failed to obtain installation token");
+  process.exit(1);
+}
+
+if (process.stdout.isTTY) {
+  console.warn("\n⚠  Token below — avoid logging this in CI or shared terminals.\n");
+}
+console.log(token);

bin/get-token.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+const command = process.argv[2];
+
+const commands = {
+  token: "./commands/token.js",
+  pull: "./commands/pull.js",
+  clone: "./commands/clone.js",
+  "check-token": "./commands/check-token.js",
+  "list-repos": "./commands/list-repos.js",
+};
+
+const help = `Usage: gh-app <command> [options]
+
+Commands:
+  token          Generate an installation token
+  pull           Pull a repo using a fresh token
+  clone          Clone a repo using a fresh token
+  check-token    Show token validity and expiry
+  list-repos     List accessible repositories
+
+Options:
+  -h, --help     Show this help message
+
+Run gh-app <command> --help for command-specific help.`;
+
+if (!command || command === "--help" || command === "-h") {
+  console.log(help);
+  process.exit(0);
+}
+
+if (!commands[command]) {
+  console.error(`Unknown command: ${command}\n`);
+  console.log(help);
+  process.exit(1);
+}
+
+// Shift argv so subcommands see their own args starting at index 2
+process.argv = [process.argv[0], process.argv[1], ...process.argv.slice(3)];
+
+await import(commands[command]);

bin/gh-app.js

@@ -0,0 +1,24 @@
+import "dotenv/config";
+import { App } from "octokit";
+import fs from "fs";
+import { resolve } from "path";
+
+export async function getInstallationAuth() {
+  const appId = process.env.GITHUB_APP_ID;
+  const installationId = process.env.GITHUB_INSTALLATION_ID;
+  const keyPath = process.env.GITHUB_PRIVATE_KEY_PATH || "./private-key.pem";
+
+  if (!appId || !installationId) {
+    console.error(
+      "Missing GITHUB_APP_ID or GITHUB_INSTALLATION_ID in environment"
+    );
+    process.exit(1);
+  }
+
+  const privateKey = fs.readFileSync(resolve(keyPath), "utf8");
+  const app = new App({ appId, privateKey });
+  const octokit = await app.getInstallationOctokit(installationId);
+  const auth = await octokit.auth({ type: "installation" });
+
+  return { octokit, token: auth.token, expiresAt: auth.expiresAt };
+}

bin/lib/auth.js

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "type": "module",
   "bin": {
-    "github-app-util": "./bin/get-token.js"
+    "gh-app": "./bin/gh-app.js"
   },
   "dependencies": {
     "dotenv": "^16.4.7",