@great-arrow/cli

中文文档
0.11.18发布于 2026/11/13SEE LICENSE IN LICENSEES Module近 30 天下载 7255

GreatArrow.ai CLI tool

原始使用文档
文档目录23 节
  1. Install
  2. Diagnostic telemetry
  3. Authentication
  4. Commands
  5. Local hardware diagnostics
  6. Memory
  7. Answer an agent's request
  8. Workspace
  9. Todos
  10. Messaging agents
  11. Decisions
  12. Repo coordination (parallel agents)
  13. Diagnostics
  14. MCP Server
  15. Agents
  16. Clear the board
  17. Operations
  18. Shell Completions
  19. Output Modes
  20. Configuration
  21. Exit Codes
  22. Development
  23. License

@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:

FlagEffect
--jsonMachine-readable JSON output
--quietData only, no decorations
--no-colorDisable 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

CodeMeaning
0Success
1Authentication error (expired token, 401/403)
2Network error (timeout, unreachable, 5xx)
3Validation 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.

版本与发布记录

@great-arrow/cli 共发布 76 个版本,首次发布于 2026/06/12;过去 12 个月发布了 76 个版本。

版本发布日期距今
0.11.18latest2026/11/133 天前
0.11.172026/11/134 天前
0.11.162026/11/116 天前
0.11.152026/11/116 天前
0.11.142026/11/106 天前
0.11.132026/11/097 天前

关于 @great-arrow/cli 的常见问题

@great-arrow/cli 是什么?

GreatArrow.ai CLI tool

如何安装 @great-arrow/cli?

在项目目录运行 npm install @great-arrow/cli,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 gad,可以用 npx gad 直接运行。

@great-arrow/cli 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/great-arrow__cli 是否存在。

@great-arrow/cli 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@great-arrow/cli 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=24.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@great-arrow/cli 可以商用吗?

@great-arrow/cli 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中,请阅读该文件确认可否商用。以上为概括,不构成法律意见,请以许可原文为准。

@great-arrow/cli 的下载量有多少?

根据 npm 官方下载统计,@great-arrow/cli 在 2026/10/17 – 2026/11/15 这 30 天内被下载 7,255 次,日均约 242 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@great-arrow/cli 还在维护吗?

最新版本 0.11.18 发布于 2026/11/13(3 天前);至今共发布 76 个版本,其中过去 12 个月发布了 76 个;首次发布于 2026/06/12。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。