@great-arrow/cli (gad)

Terminal-based access to the Great Arrow Digital platform — memory management, workspace administration, integration diagnostics, MCP tooling, and deployment operations.

Install

npm install -g @great-arrow/cli

Requires Node.js 24+.

Authentication

# Browser login (loopback OAuth + PKCE). Opens your browser, captures the
# callback locally, and stores a refreshable credential — no copy-paste.
# The session refreshes itself; you won't be asked to log in again until the
# refresh token expires.
gad login

# If a browser can't be opened (SSH/remote), print the URL to open manually
gad login --no-browser

# Direct personal token (CI/CD, headless). Stored as-is; no auto-refresh.
gad login --token gad_xxxxx

# Check who you are (shows auth type + access-token expiry)
gad whoami

# Revoke the session server-side and remove stored credentials
gad logout

Credentials live in your OS keychain (Keychain Access / libsecret / Credential Vault). OAuth access tokens are short-lived and refreshed automatically; GAD_TOKEN in the environment always takes precedence for CI.

Tokens are stored in the OS keychain (macOS Keychain / Windows Credential Manager / Linux Secret Service). You can also set GAD_TOKEN as an environment variable.

Commands

Memory

gad memory create --title "API design decision" --content "We chose REST over GraphQL because..."
gad memory search "authentication flow"
gad memory list --layer SEMANTIC --tag auth
gad memory get <id>
gad memory delete <id>

# Pipe content from stdin
cat notes.md | gad memory create --title "Meeting notes"

Workspace

gad workspace list
gad workspace switch my-project
gad workspace info
gad workspace members

Todos

gad todo list
gad todo list --status in_progress
gad todo create "Fix login bug" --priority high --due 2026-06-05
gad todo done <id>
gad todo update <id> --status review

Repo coordination (parallel agents)

# Start a task the safe way: a FRESH worktree on a new branch off the origin
# default branch, with a real dependency install. Refuses in a dirty tree.
gad worktree new feat/fix-login            # creates ../<repo>-fix-login
gad worktree new feat/fix-login ../my-dir  # explicit target dir
gad worktree new feat/fix-login --no-install

# Install the fail-open agent commit guard into this repo's pre-commit hook
# (.husky/pre-commit when husky is present, else .git/hooks/pre-commit).
# Idempotent — re-running never duplicates the hook block.
gad install-hooks

gad worktree new stamps the creating agent session as the worktree owner. The guard installed by gad install-hooks walks the committer's PID ancestry at commit time: if the worktree's owner is a different, still-live agent session, the commit is blocked (you were about to commit another agent's in-flight work). Every ambiguity — no owner marker, dead owner, human committer — fails open, so it can never block a legitimate commit. Deliberate override: ALLOW_FOREIGN_WORKTREE=1.

Diagnostics

# Full health check (token, API, integrations, MCP)
gad doctor

# Integration management
gad integrations list
gad integrations sync github

MCP Server

gad mcp status
gad mcp logs
gad mcp test

# Generate MCP config for your AI client
gad mcp install claude
gad mcp install cursor
gad mcp install kiro
gad mcp install codex
gad mcp install gemini

gad mcp install codex writes Codex's native ~/.codex/config.toml server entry and stores the bearer token in ~/.codex/.env.

Keeping local MCP installs current

Great Arrow checks local MCP/CLI versions from the headers and user-agent hints sent by installed configs, the gad CLI, and the stdio proxy. When a local agent is stale, the recommended path for users is Account → Connections in the web app, then the agent's Update, Update now, or Check setup button. That flow provides client-specific repair steps without requiring the user to understand MCP config files.

Terminal fallback:

npm install -g @great-arrow/cli@latest
gad doctor
gad mcp install codex   # replace codex with claude, cursor, kiro, or gemini

Use gad doctor after repair to confirm API access, token metadata capture, and MCP reachability.

Agents

gad agent list
gad agent invoke research-analyst --task "Summarize Q2 metrics"
gad ask "What did we decide about the caching layer?"

Deployment & Operations

gad deploy              # Interactive confirmation
gad deploy --confirm    # CI/CD (no prompt)
gad migrate             # Run pending DB migrations
gad smoke               # MCP smoke test suite

Shell Completions

gad completions bash >> ~/.bashrc
gad completions zsh >> ~/.zshrc
gad completions fish > ~/.config/fish/completions/gad.fish

Output Modes

All list/query commands support:

| Flag | Effect | | ------------ | ---------------------------- | | --json | Machine-readable JSON output | | --quiet | Data only, no decorations | | --no-color | Disable ANSI colors |

When stdout is not a TTY (piped), colors and interactive prompts are automatically disabled.

Configuration

Optional config file at ~/.gadrc:

api_url = https://www.greatarrowdigital.com
default_workspace = my-project
output_format = table
token = gad_xxxxx

Precedence: GAD_TOKEN env → OS keychain → .gadrc file.

Exit Codes

| Code | Meaning | | ---- | --------------------------------------------- | | 0 | Success | | 1 | Authentication error (expired token, 401/403) | | 2 | Network error (timeout, unreachable, 5xx) | | 3 | Validation error (missing args, bad input) |

Development

# From the repo root
cd packages/cli

# Run tests
pnpm test

# Build (single-file ESM bundle)
pnpm build

# Type check
pnpm typecheck

License

Proprietary — see root LICENSE.