CLI Commands
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.
genaug --versiongenaug auth login --api-key gaadmlive_your_key_heregenaug doctorgenaug auth whoamigenaug auth logoutgenaug 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
Section titled “Projects”genaug projects listgenaug projects create \ --name "Demo Agent" \ --slug demo-agent \ --system-prompt "You help users answer product questions."genaug status --project demo-agentgenaug projects usage \ --project demo-agent \ --start-date 2026-04-01 \ --end-date 2026-04-24genaug projects export \ --project demo-agent \ --include config \ --include logs \ --output artifacts/demo-project-export.jsongenaug projects archive demo-agent --yesgenaug 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
Section titled “Billing”genaug billing status --project demo-agentgenaug billing top-up --project demo-agent --amount-usd 25.00genaug billing top-up --project demo-agent --amount-usd 50.00 --save-payment-method --jsongenaug billing usage --project demo-agent --start-date 2026-05-01 --end-date 2026-05-09 --jsongenaug billing verify --project demo-agent --jsongenaug billing checkout --project demo-agent --tier progenaug billing checkout --project demo-agent --tier team --jsongenaug billing portal --project demo-agentgenaug billing events --project demo-agent --jsongenaug 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
Section titled “API keys”genaug keys create --project demo-agent --name "Production backend"genaug keys listgenaug keys update <key-id> --name "Production backend 2026-04 rotation"genaug keys revoke <key-id>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
Section titled “API integration”If you do not have an OpenAPI spec yet, start with a local agent scaffold:
genaug init demo-agent \ --display-name "Demo Agent" \ --description "Demo assistant" \ --tool web_searchgenaug validate ./demo-agent/genaug-agent.yamlgenaug dev ./demo-agent/genaug-agent.yaml --message "What can you help me with?"genaug deploy ./demo-agent/genaug-agent.yamlgenaug 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.
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-deploygenaug tools list --project demo-agentgenaug tools toggle delete_account --project demo-agent --disablegenaug 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
Section titled “App smoke checks”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-agentgenaug 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
Section titled “Project verification”genaug verify --project demo-agentgenaug onboarding verify --project demo-agent --jsongenaug 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 calledPOST /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/responseswith 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:
uv run python scripts/dashboard-cli-tenant-smoke.pyIt 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
Section titled “Runtime Policy”genaug projects runtime-policy --project demo-agentgenaug projects runtime-policy --project demo-agent --jsongenaug tools discovery --project demo-agent --mode always --jsonUse 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
Section titled “Model providers”genaug model-providers list --project demo-agentgenaug 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 --jsongenaug model-providers revoke openai --project demo-agent --yesUse 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
Section titled “Skills”genaug skills list --project demo-agentgenaug skills view "Schedule Meeting" --project demo-agentgenaug skills apply ./skills/schedule-meeting/SKILL.md --project demo-agentgenaug skills delete "Schedule Meeting" --project demo-agentUse genaug skills apply to create or replace a tenant SKILL.md file without
redeploying the whole agent manifest.
MCP servers
Section titled “MCP servers”genaug mcp list --project demo-agentgenaug mcp add github \ --project demo-agent \ --url https://mcp.github.example.com/mcp \ --header 'Authorization=Bearer ${{ secrets.GITHUB_TOKEN }}' \ --include-tool search_reposgenaug mcp test github --project demo-agentgenaug mcp delete github --project demo-agentUse 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
Section titled “Memory”genaug memory store \ "User prefers concise onboarding notes." \ --project demo-agent \ --user app-user-123 \ --fact-type preference \ --idempotency-key memory-app-user-123-onboardinggenaug memory search \ --project demo-agent \ --user app-user-123 \ --query "onboarding notes" \ --jsongenaug memory profile --project demo-agent --user app-user-123genaug memory delete <memory-id> --project demo-agent --user app-user-123genaug memory purge-user --project demo-agent --user app-user-123 --yesThese 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
Section titled “Users and identity”genaug users list --project demo-agentgenaug users detail <general-augment-user-id> --project demo-agent --jsongenaug users delete <general-augment-user-id> --project demo-agent --yes
genaug identity list --project demo-agentgenaug identity create-test \ --project demo-agent \ --phone "+15551234567" \ --provider-name demo \ --provider-user-id "auth0|user_123" \ --metadata source=staging-smoke \ --jsongenaug identity link-user \ --project demo-agent \ --phone "+15551234567" \ --provider-name demo \ --provider-user-id "auth0|user_123" \ --metadata source=settings-page \ --jsongenaug identity verification-code \ --project demo-agent \ --phone "+15551234567" \ --provider-name demo \ --provider-user-id "auth0|user_123" \ --jsongenaug identity magic-link \ --project demo-agent \ --phone "+15551234567" \ --provider-name demo \ --user-identifier person@example.com \ --channel whatsapp \ --jsongenaug identity verify \ --project demo-agent \ --phone "+15551234567" \ --provider-name demo \ --code "123456" \ --jsongenaug identity resolve \ --project demo-agent \ --phone "+15551234567" \ --provider-name demo \ --jsongenaug identity unlink \ --project demo-agent \ --phone "+15551234567" \ --provider-name demo \ --yesUse 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
Section titled “Observability and support bundles”genaug observability trace trace_abc123 --project demo-agentgenaug 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.jsonUse 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
Section titled “Scheduled Jobs”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 \ --jsongenaug jobs list --project demo-agent --status active --jsongenaug jobs detail "$GENAUG_SCHEDULED_JOB_ID" --project demo-agent --jsongenaug jobs runs "$GENAUG_SCHEDULED_JOB_ID" --project demo-agent --jsongenaug jobs run "$GENAUG_SCHEDULED_JOB_ID" \ --project demo-agent \ --dispatch-key operator-smoke-1 \ --record-only \ --jsongenaug jobs pause "$GENAUG_SCHEDULED_JOB_ID" --project demo-agent --jsongenaug jobs resume "$GENAUG_SCHEDULED_JOB_ID" --project demo-agent --jsongenaug jobs delete "$GENAUG_SCHEDULED_JOB_ID" --project demo-agent --yes --jsongenaug 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
Section titled “Approvals”genaug approvals list --project demo-agentgenaug approvals list --project demo-agent --status all --jsongenaug approvals approve approval_abc123 --project demo-agent --yesgenaug approvals deny approval_abc123 --project demo-agent --yes --jsonUse 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
Section titled “Channels”genaug channels status --project demo-agentgenaug 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 \ --yesgenaug 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
Section titled “Local iteration”genaug dev ./demo-agent/genaug-agent.yaml --message "Help me prepare onboarding notes"genaug mock --host 127.0.0.1 --port 8787 --quietgenaug 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.
genaug logs --project demo-agent --followThe 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 for the HTTP contract behind these commands.