# CLI Commands Source: https://docs.generalaugment.com/cli/commands/ Description: Common commands for integrating and operating projects. Use this page as a command reference. Guides keep copyable examples short; the reference uses the neutral placeholder project `demo-agent`. Replace it with your project slug. ## Auth ```bash genaug --version genaug auth login --api-key gaadmlive_your_key_here genaug doctor genaug auth whoami genaug auth logout ``` `genaug doctor` checks local config, the resolved API URL, API-key presence, `/health/ready`, and `/api/v1/admin/me` without printing secret values. Run it first when a developer is blocked before project setup. ## Projects ```bash genaug projects list genaug projects create \ --name "Demo Agent" \ --slug demo-agent \ --system-prompt "You help users answer product questions." genaug status --project demo-agent genaug projects usage \ --project demo-agent \ --start-date 2026-04-01 \ --end-date 2026-04-24 genaug projects export \ --project demo-agent \ --include config \ --include logs \ --output artifacts/demo-project-export.json genaug projects archive demo-agent --yes ``` `genaug projects export` writes the bounded project export returned by the admin API. It can include safe config, usage rollups, retained logs, trace summaries, audit rows, memory facts, and usage events depending on the server-side retention window and the `--include` filters. It does not include raw credentials, API keys, provider tokens, memory embeddings, or unredacted tool payloads. `genaug projects archive` changes the project status to archived. It is not a hard delete and prompts for confirmation unless `--yes` is supplied. ## Billing ```bash genaug billing status --project demo-agent genaug billing top-up --project demo-agent --amount-usd 25.00 genaug billing top-up --project demo-agent --amount-usd 50.00 --save-payment-method --json genaug billing usage --project demo-agent --start-date 2026-05-01 --end-date 2026-05-09 --json genaug billing verify --project demo-agent --json genaug billing checkout --project demo-agent --tier pro genaug billing checkout --project demo-agent --tier team --json genaug billing portal --project demo-agent genaug billing events --project demo-agent --json ``` `genaug billing status` shows credit balance, grant/reservation counts, funding mode, and auto top-up state. `genaug billing top-up` creates a hosted Stripe Checkout session for paid usage credits. `genaug billing usage` returns billing-relevant usage rollups for reconciliation. `genaug billing verify` checks the credit gate, funding mode, credit ledger reservation linkage, and usage rollup visibility for operator preflight. `genaug billing checkout` creates a hosted Stripe Checkout session for Build, Pro, or Team through the General Augment admin API. `genaug billing portal` creates a hosted Stripe Customer Portal session for a linked customer. `genaug billing events` lists recent stored Stripe lifecycle events for the project, including checkout completion, subscription changes, invoice paid events, and payment failures. The commands are secret-free and return hosted URLs or stored event metadata, not Stripe keys. ## API keys ```bash genaug keys create --project demo-agent --name "Production backend" genaug keys list genaug keys update --name "Production backend 2026-04 rotation" genaug keys revoke ``` The raw API key is printed only when created. Store it in your app backend secret manager, then use `genaug verify --project demo-agent` to confirm the same tenant is working before checking the dashboard. ## API integration If you do not have an OpenAPI spec yet, start with a local agent scaffold: ```bash genaug init demo-agent \ --display-name "Demo Agent" \ --description "Demo assistant" \ --tool web_search genaug validate ./demo-agent/genaug-agent.yaml genaug dev ./demo-agent/genaug-agent.yaml --message "What can you help me with?" genaug deploy ./demo-agent/genaug-agent.yaml ``` `genaug init` writes `genaug-agent.yaml`, `SOUL.md`, `skills/`, `tools/`, `.env.example`, and `CODING_AGENT_PROMPT.md` without calling the hosted API. Repeated `--tool` values enable built-in tools in the starter manifest; MCP servers and generated OpenAPI tools should still be added through `genaug mcp add` or `genaug integrate` so the tenant-visible tool surface stays explicit, allowlisted, and auditable. `genaug validate` checks the local manifest, model tiers, SOUL/skills paths, tool-discovery bounds, and MCP secret-placeholder hygiene before deploy. `genaug deploy` runs the same local validation and stops before the hosted API call when the manifest has errors. ```bash genaug integrate https://api.example.com/openapi.json \ --name demo-agent \ --description "Demo assistant" genaug deploy ./demo-agent/genaug-agent.yaml genaug integrate https://api.example.com/openapi.json \ --name demo-agent \ --description "Demo assistant" \ --auto-deploy genaug tools list --project demo-agent genaug tools toggle delete_account --project demo-agent --disable genaug tools discovery \ --project demo-agent \ --mode auto \ --direct-schema-tool-limit 10 \ --max-search-results 5 ``` `--auto-deploy` creates or updates the project and registers the curated OpenAPI tools against it; do not run a second deploy afterward unless you make local changes. Omit the flag when you want to inspect and validate the generated files before deploy. ## App smoke checks ```bash genaug smoke \ --message "Reply exactly with: genaug-smoke-ok" \ --idempotency-key smoke-replay-1 \ --request-id req_smoke_1 \ --project demo-agent \ --metadata feature=demo genaug smoke \ --structured \ --message 'Return JSON with ok=true and label="genaug-smoke-ok".' \ --project demo-agent ``` `genaug smoke` checks `/health/ready` and sends one project-keyed `/v1/responses` request using bearer auth. The human output includes a redacted support receipt. Add `--json` when you need one machine-readable object with the readiness payload, full response, `response_id`, `request_id`, `trace_id`, and `support_receipt` for replay or support debugging. Use `--project` when your configured credential is a management key instead of a project-scoped app key. Use `--structured` for the default schema smoke, or `--schema-file ./schema.json` to send an app-owned JSON Schema through the same contract. ## Project verification ```bash genaug verify --project demo-agent genaug onboarding verify --project demo-agent --json ``` `genaug verify` checks API readiness, resolves the project, confirms a project-scoped API key exists, runs the hosted agent test endpoint, verifies tools, logs, usage, usage limits, observability, runtime policy model routing, SOUL visibility, tenant skill visibility, memory lifecycle, and tool-call audit endpoints, then prints the dashboard URLs to inspect for the same tenant. JSON output includes `runtime_policy.model_routing` with simple, balanced, and complex tiers plus `channel_parity=true`. The `project_key_execution` check is explicit in JSON output: - `PASS`: the CLI is authenticated with a project-scoped key for this tenant and that key successfully called `POST /v1/responses`. - `SKIP`: the configured CLI key is broader admin or management auth. The run confirmed a project key exists, but did not execute `/v1/responses` with that project key. - `FAIL`: the configured project-scoped key could not complete the Responses call. Use `genaug onboarding verify --project demo-agent --json` as the coding-agent friendly final gate. Keep that JSON with release evidence because it includes CLI/API version metadata, auth scope, dashboard URLs, usage limits, and per-check status without printing raw keys. For rate-limit `429` responses, CLI errors include the platform's stable reason and `Retry-After` timing when available. When operating from the repository, use the dashboard CLI tenant smoke for full CLI-to-dashboard proof: ```bash uv run python scripts/dashboard-cli-tenant-smoke.py ``` It creates a fresh dummy tenant, deploys a skill, sends sentinel `/v1/responses` requests, runs `genaug verify --json`, proves generated tool governance, SOUL/skill behavior, multi-user memory API isolation, and Responses memory-context scoping, starts an owned local dashboard server, and saves JSON evidence plus screenshots for the same tenant. Trace/support-bundle retrieval, installed CLI/SDK compatibility comparison, and autonomous memory final-answer behavior are launch-proofed only when the artifact explicitly records passing evidence. Set `GENAUG_DASHBOARD_SMOKE_ARCHIVE_PROJECT=1` for CI cleanup after evidence is captured. ## Runtime Policy ```bash genaug projects runtime-policy --project demo-agent genaug projects runtime-policy --project demo-agent --json genaug tools discovery --project demo-agent --mode always --json ``` Use this before launch reviews to inspect model-routing tiers, channel parity, tool discovery mode, enabled platform tools, MCP tool IDs, and skill names for the same tenant. ## Model providers ```bash genaug model-providers list --project demo-agent genaug model-providers set openai \ --project demo-agent \ --api-key-env OPENAI_API_KEY \ --api-mode responses \ --model-prefix openai/ genaug model-providers health openai --project demo-agent --json genaug model-providers revoke openai --project demo-agent --yes ``` Use these commands when a tenant wants General Augment model routing to use their provider account. `set` stores or rotates the provider key through the server-side credential vault. Omit `--api-key` to enter a hidden prompt, or prefer `--api-key-env` for automation so raw keys do not appear in shell history. List, health, and revoke responses are secret-free and never return the stored provider key. The public `--api-mode responses` alias maps to Hermes's internal `codex_responses` transport; use the alias in tenant docs and scripts unless you are debugging Hermes internals. ## Skills ```bash genaug skills list --project demo-agent genaug skills view "Schedule Meeting" --project demo-agent genaug skills apply ./skills/schedule-meeting/SKILL.md --project demo-agent genaug skills delete "Schedule Meeting" --project demo-agent ``` Use `genaug skills apply` to create or replace a tenant SKILL.md file without redeploying the whole agent manifest. ## MCP servers ```bash genaug mcp list --project demo-agent genaug mcp add github \ --project demo-agent \ --url https://mcp.github.example.com/mcp \ --header 'Authorization=Bearer ${{ secrets.GITHUB_TOKEN }}' \ --include-tool search_repos genaug mcp test github --project demo-agent genaug mcp delete github --project demo-agent ``` Use `genaug mcp add` for tenant-owned MCP servers. Provide exactly one transport: `--url` for HTTP MCP endpoints or `--command` plus repeated `--arg` values for stdio servers. Sensitive headers and environment values must be credential placeholders such as `${{ secrets.GITHUB_TOKEN }}` or `${{ credentials.github_token }}`. Use `--include-tool` and `--exclude-tool` to keep the Hermes-visible tool surface scoped. ## Memory ```bash genaug memory store \ "User prefers concise onboarding notes." \ --project demo-agent \ --user app-user-123 \ --fact-type preference \ --idempotency-key memory-app-user-123-onboarding genaug memory search \ --project demo-agent \ --user app-user-123 \ --query "onboarding notes" \ --json genaug memory profile --project demo-agent --user app-user-123 genaug memory delete --project demo-agent --user app-user-123 genaug memory purge-user --project demo-agent --user app-user-123 --yes ``` These commands call the same tenant memory API your app backend uses. Pass `--project` when the configured credential is a management key. Omit it only when the key is already project-scoped. Use `--json` for automation and support evidence. ## Users and identity ```bash genaug users list --project demo-agent genaug users detail --project demo-agent --json genaug users delete --project demo-agent --yes genaug identity list --project demo-agent genaug identity create-test \ --project demo-agent \ --phone "+15551234567" \ --provider-name demo \ --provider-user-id "auth0|user_123" \ --metadata source=staging-smoke \ --json genaug identity link-user \ --project demo-agent \ --phone "+15551234567" \ --provider-name demo \ --provider-user-id "auth0|user_123" \ --metadata source=settings-page \ --json genaug identity verification-code \ --project demo-agent \ --phone "+15551234567" \ --provider-name demo \ --provider-user-id "auth0|user_123" \ --json genaug identity magic-link \ --project demo-agent \ --phone "+15551234567" \ --provider-name demo \ --user-identifier person@example.com \ --channel whatsapp \ --json genaug identity verify \ --project demo-agent \ --phone "+15551234567" \ --provider-name demo \ --code "123456" \ --json genaug identity resolve \ --project demo-agent \ --phone "+15551234567" \ --provider-name demo \ --json genaug identity unlink \ --project demo-agent \ --phone "+15551234567" \ --provider-name demo \ --yes ``` Use `genaug users` from trusted operator machines to inspect user activity, memory counts, and connected credential summaries without printing raw tokens. `genaug users delete` cascades tenant user data and requires `--yes` for noninteractive runs. Use `genaug identity create-test` to create or update a verified test link between a channel phone number and a tenant app user before exercising identity-aware tools. Use `genaug identity link-user`, `verification-code`, `magic-link`, `verify`, `resolve`, and `unlink` from trusted operator machines or backend automation when support needs to exercise the same server-side integration APIs documented in `IDENTITY-LINKING.md`. These commands use the configured admin API key and do not host browser-facing user auth. ## Observability and support bundles ```bash genaug observability trace trace_abc123 --project demo-agent genaug observability trace trace_abc123 --project demo-agent --json genaug observability support-bundle \ --project demo-agent \ --trace-id trace_abc123 \ --response-id resp_abc123 \ --status failure \ --output artifacts/demo-support-bundle.json ``` Use `genaug observability trace` when your app stored `metadata.trace_id` from a Responses turn and you need the local project-scoped turn record. Use `genaug observability support-bundle` for launch reviews and incident debugging; it exports the bounded, retained trace/log/audit/memory/usage timeline assembled by the admin API. Trace and support artifacts include Hermes skill names used or created when that evidence is available from the tenant runtime. Terminal output shows counts only by default. Use `--json` or `--output` when you need the full support artifact. ## Scheduled Jobs ```bash genaug jobs create \ --project demo-agent \ --target-app-user-id app-user-123 \ --name "Daily account review" \ --prompt "Review this account and summarize the next action." \ --interval-seconds 3600 \ --json genaug jobs list --project demo-agent --status active --json genaug jobs detail "$GENAUG_SCHEDULED_JOB_ID" --project demo-agent --json genaug jobs runs "$GENAUG_SCHEDULED_JOB_ID" --project demo-agent --json genaug jobs run "$GENAUG_SCHEDULED_JOB_ID" \ --project demo-agent \ --dispatch-key operator-smoke-1 \ --record-only \ --json genaug jobs pause "$GENAUG_SCHEDULED_JOB_ID" --project demo-agent --json genaug jobs resume "$GENAUG_SCHEDULED_JOB_ID" --project demo-agent --json genaug jobs delete "$GENAUG_SCHEDULED_JOB_ID" --project demo-agent --yes --json ``` `genaug jobs` manages the same project-scoped scheduled jobs as the admin API. JSON output is stable for automation and includes next/last run timestamps, retry history, terminal reason, target user/channel, latest trace ID, and linked durable run IDs. `delete` cancels the job and keeps execution history for audit. `run --record-only` creates a dispatch record without executing Hermes; omit it for a live validation run. ## Approvals ```bash genaug approvals list --project demo-agent genaug approvals list --project demo-agent --status all --json genaug approvals approve approval_abc123 --project demo-agent --yes genaug approvals deny approval_abc123 --project demo-agent --yes --json ``` Use `genaug approvals list` to inspect governed tool requests such as email sends, calendar writes, and generated mutating API calls. `approve` and `deny` call the same project-scoped admin endpoints as the dashboard and enqueue the existing approval-resume workflow when the request is still pending. They prompt for confirmation unless `--yes` is supplied for automation. ## Channels ```bash genaug channels status --project demo-agent genaug channels connect \ --project demo-agent \ --channel telegram \ --bot-token "$TELEGRAM_BOT_TOKEN" genaug channels connect \ --project demo-agent \ --channel whatsapp \ --phone-number-id "$WHATSAPP_PHONE_NUMBER_ID" genaug channels connect \ --project demo-agent \ --channel sms \ --twilio-number "+15551234567" genaug channels test \ --project demo-agent \ --channel telegram \ --chat-id "$TELEGRAM_CHAT_ID" \ --message "General Augment test" genaug channels disconnect \ --project demo-agent \ --channel telegram \ --yes ``` `genaug channels connect` can configure Telegram, WhatsApp, and SMS sender records; `genaug channels disconnect` can clear them. `genaug channels test` currently sends provider test messages for Telegram only. `genaug channels status --json` reports Telegram provider status plus saved WhatsApp/SMS identifiers for automation. WhatsApp and SMS still require their provider webhook settings from the channel guides before inbound messages can route. Tenant-owned local connectors, such as a Mac-backed iMessage connector or private VM connector, are configured through `connectors.local` in `genaug-agent.yaml` and the local connector scripts. They are not configured with `genaug channels connect`. ## Local iteration ```bash genaug dev ./demo-agent/genaug-agent.yaml --message "Help me prepare onboarding notes" genaug mock --host 127.0.0.1 --port 8787 --quiet ``` `genaug mock` starts the deterministic local HTTP mock for app backend contract tests. Point app tests at `http://127.0.0.1:8787` with a local-only API key to exercise Responses, memory routes, project setup, OpenAPI tool registration, key management, logs, usage, observability, health checks, idempotency replays, trace metadata, structured-output fixtures, and SSE fixtures without live provider calls. ## Logs ```bash genaug logs --project demo-agent --follow ``` The CLI covers the standard developer path: auth, project operations, generated API integrations, tool and channel setup, status and logs, local config iteration, and offline local mock testing. See the generated [API reference](/api/) for the HTTP contract behind these commands.