@great-arrow/cli (gad)
Terminal-based access to the Great Arrow Digital platform — memory management, workspace administration, integration diagnostics, and MCP tooling.
Install
npm install -g @great-arrow/cli
Requires Node.js 24+.
Diagnostic telemetry
CLI diagnostics are opt-in. Enable with GAD_TELEMETRY=1 for a session or set
telemetry_enabled = true in ~/.gadrc; disable with GAD_TELEMETRY=0.
Only bounded command, network, and MCP failure metadata is sent. Credentials,
cookies, paths, and email-like fields are redacted; telemetry failures never
affect command behavior.
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.
# Over a signed-in OAuth session it takes a gad_v1_ token, keeps the session
# when handed the session's own access token, and otherwise needs --force.
gad login --token gad_v1_xxxxx
# Check who you are (shows auth type + access-token expiry)
gad whoami
# Revoke the session server-side and remove stored credentials
gad logout
# For tools, not humans: print a fresh access token through the CLI's locked
# refresh path (~/.great-arrow/refresh.lock), so other programs never refresh
# this credential themselves. --json prints {accessToken, accessExpiresAt,
# apiUrl}. Exit 2: session expired or not signed in. Exit 3: the stored
# credential is a personal token (nothing to refresh).
gad auth token [--json]
Credentials live in your mode-0600 ~/.great-arrow/credential store (inside
0700 ~/.great-arrow/) and/or your OS keychain (Keychain Access / libsecret /
Credential Vault). Keeping ~/.great-arrow/credential synced and reading it
first avoids repeated macOS Keychain cdhash password prompts when multiple
Node.js versions (nvm, volta, Homebrew) or the stdio MCP proxy access
automatically refreshed OAuth tokens. GAD_TOKEN in the environment always
takes precedence for CI.
Commands
Local hardware diagnostics
gad local doctor reads this computer's RAM and available space on the home volume. Use --json for structured observations or --quiet to suppress the human report. It does not sign in, download models, load a model, enroll a device or change settings.
Free RAM is an operating-system observation, not usable model capacity. Graphics memory and model compatibility remain unqualified until their separate checks run. Home-volume space may differ from a custom Ollama model location. The filesystem probe stops waiting after three seconds and reports unavailable rather than zero.
This command is being implemented under T04; source and local build checks do not establish a published installer or completed setup.
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 update <id> --title "Reviewed note" --expected-version 4
gad memory delete <id>
# Pipe content from stdin
cat notes.md | gad memory create --title "Meeting notes"
gad memory update changes supported metadata through the same memory_update
tool used by MCP and the web app. It accepts --title, --layer,
--importance (0–1), --status (ACTIVE or ARCHIVED), --tags (a
comma-separated replacement set; pass "" to clear), and --verified.
Pass --expected-version from gad memory get to refuse stale edits. Deletion
stays on gad memory delete, which asks for confirmation unless --confirm is
passed.
Answer an agent's request
gad answer <message-id> --accept --message "Use staging first"
gad answer <message-id> --decline --message "Not this week"
Decides a request an agent addressed to you and tells the asking agent the outcome. It works from a browser gad login only; a --token login is refused.
gad memory search shows a Source column for every hit: the original
document's link (GitHub, Notion, Drive…) when there is one, otherwise the
memory's page in the web app. gad ask prints a numbered Sources list of
the memories its answer was built from, under the answer (--quiet hides it;
--json keeps the raw hits).
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
gad todo create "Review the PR" --external-agent skippy # --me | --specialist <key> | --agent <id> | --external-agent <name|id>
gad todo assign <id> --external-agent skippy # a connected agent, by name, alias or connection id
gad todo assign <id> --device "Studio Mac" --adapter claude-code # prints the passkey approval link; nothing starts until you approve
gad todo comment <id> "Take this one" --mention skippy # hands the card to that agent
Assignment is passive: an in-platform agent is queued, never started, until you
run gad todo run <id>. Names resolve through agents_now (gad agents); an
ambiguous name lists the matching connection ids.
Messaging agents
gad send conductor "Anything blocking the train?"
gad send codex "Can you take #7270?" --request # queues a request it accepts or declines
gad send human "Done, ready for review" --reply-to <message id>
gad send <agent> <message> calls the same agent_message_send tool MCP
agents use; <agent> is a surface name, human, conductor or a session id.
Decisions
gad decide # what is waiting on you
gad decide <id> # the question and its options
gad decide <id> --choose Approve # pick an option by id or label
gad decide <id> --other "..." # answer in your own words
gad decide <id> --context "..." # add a note or question; it stays open
gad decide <id> --undo # take an answer back
A terminal token is the same credential an agent shell holds, so an answer from here is recorded as coming from this connection, not as your personal decision. The command prints the signed-in page to use when it should count as yours.
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
# Claude Code surface: server entry, hook wiring, hook credential — and
# whether every hook you have CONFIGURED can actually run. That last check
# reads all four settings scopes (managed, user, project, local), because a
# hook that cannot execute fails silently on every single session and no
# repo-side test can see your user or local file.
gad doctor claude
gad doctor claude --enforce # back up and repair what is repairable
# It checks the same four Claude Code hooks /install/pair installs (transcript
# Stop, session glance, war-room, live activity). --enforce installs any that
# are missing by running that hook's own --install, so a repaired machine and
# a freshly paired one end up wired identically.
# Integration management
gad integrations list
gad integrations sync github
MCP Server
# Run a local stdio MCP server bridging to the hosted Great Arrow endpoint.
# This is what AI clients configured with `npx -y @great-arrow/cli mcp start`
# execute. Auth: GAD_API_TOKEN env → GAD_TOKEN env → stored `gad login`
# credential. For one-off credentials, see `gad mcp start --help`.
gad mcp start
gad mcp status
gad mcp logs
gad mcp test
# Audit every Great Arrow MCP connection on this machine: duplicate entries per
# client (with the most capable one to keep and the exact command to drop the
# rest), credential stores, and live reachability. `--migrate` copies the newest
# valid legacy per-cwd credential into the per-user store and writes the
# keychain credential to the file the stdio proxy reads first.
gad mcp doctor
gad mcp doctor --migrate
gad mcp doctor --json
# 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
Optional: tool suggestions in Claude Code (off by default)
gad mcp suggest-tools on # shows what is sent, then asks [y/N]
gad mcp suggest-tools on --yes # non-interactive opt-in
gad mcp suggest-tools off # removes only this hook's entry
gad mcp suggest-tools status
gad mcp install claude --suggest-tools # or --no-suggest-tools
When on, a Claude Code UserPromptSubmit hook sends each prompt's text (up to
2,000 characters, nothing else) to greatarrow.ai over your own token and adds
up to three Great Arrow tool names that may help. The prompt is not stored or
logged; the hook gives up after 1.5 seconds and never blocks a prompt. It adds
one entry to ~/.claude/settings.json and reads its token from
~/.great-arrow/hook-config.json — never from argv or settings.json.
gad doctor claude reports whether it is on.
gad mcp install codex writes Codex's native ~/.codex/config.toml server
entry and stores the bearer token in ~/.codex/.env. The entry launches the
stdio bridge, which detects the current checkout's git origin for every Codex
session; it does not pin one repository in the global config.
Workspace targeting precedence is explicit command target, current git repo, then the saved default outside a repo:
# One command only; accepts an id, slug, or exact name.
gad --workspace great-arrow-digital todo list
# Save a default and see the previous/current workspace in the confirmation.
gad workspace switch great-arrow-digital
# Inside a linked git checkout, the repo workspace wins over that saved default.
gad workspace list
workspace_list and tools_discover are compact by default. MCP callers can
request detail:"full" when diagnostics are needed; when a stable tool name is
known, tools_discover({ tool_name: exactName }) returns one schema without
walking the full catalog or performing session/recommendation datastore reads.
High-frequency todo_log and work_heartbeat calls skip the enrichment batch
and render a single branded line, preserving the current workspace cue without
repeating board/status payloads.
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, gemini, or muse
Use gad doctor after repair to confirm API access, token metadata capture,
and MCP reachability.
Agents
gad agents # who is working right now, and where
gad agent list
gad agent invoke research-analyst --task "Summarize Q2 metrics"
gad ask "What did we decide about the caching layer?"
Clear the board
gad board clear # preview a run: audit, quote, nothing changes
gad board clear --yes # start it (hosted agent unless you pick your computer)
gad board run # work an approved run's cards here, with your own agent
gad board run --agent codex --yes # pick Codex; --yes skips the y prompt
gad board clear --here # plan, start and work the run in this terminal
gad board run lists the cards your run chose for this computer, with three
lines of each, and asks y (or v to read them in full) once. Your own Claude
Code or Codex then works each card in a sandboxed worktree. The terminal
commits and pushes gad/run-<run8>-<card8>; Great Arrow opens the pull request
and lands it. Ctrl-C stops safely; running the same command goes on with the
remaining cards. Needs
macOS, Linux with bubblewrap, or WSL. Run it inside a checkout of the run's
repository. See docs/reference/BOARD_AUTOPILOT.md for the details.
Operations
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.greatarrow.ai
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.