@great-arrow/cli 0.1.0

package/README.md

@@ -0,0 +1,171 @@
+# @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
+
+```bash
+npm install -g @great-arrow/cli
+```
+
+Requires **Node.js 20+**.
+
+## Authentication
+
+```bash
+# Browser-based login (opens token minting page)
+gad login
+
+# Direct token (CI/CD)
+gad login --token gad_xxxxx
+
+# Check who you are
+gad whoami
+
+# Remove stored credentials
+gad logout
+```
+
+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
+
+```bash
+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
+
+```bash
+gad workspace list
+gad workspace switch my-project
+gad workspace info
+gad workspace members
+```
+
+### Todos
+
+```bash
+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
+```
+
+### Diagnostics
+
+```bash
+# Full health check (token, API, integrations, MCP)
+gad doctor
+
+# Integration management
+gad integrations list
+gad integrations sync github
+```
+
+### MCP Server
+
+```bash
+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`.
+
+### Agents
+
+```bash
+gad agent list
+gad agent invoke research-analyst --task "Summarize Q2 metrics"
+gad ask "What did we decide about the caching layer?"
+```
+
+### Deployment & Operations
+
+```bash
+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
+
+```bash
+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`:
+
+```ini
+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
+
+```bash
+# 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](../../LICENSE).