Skip to content

automation.md

Latest commit

 

History

History
1164 lines (935 loc) · 41.6 KB

automation.md

File metadata and controls

1164 lines (935 loc) · 41.6 KB
Raw
title Automation Contract

Automation Contract

This document defines the machine-consumption contract for Agora CLI.

Use this guide for:

  • CI jobs
  • shell scripts
  • agentic workflows
  • editor or IDE integrations

Contents

General Rules

  • Prefer --json for any command consumed by code, scripts, or agents.
  • Prefer agora init for end-to-end setup.
  • Use low-level commands when a workflow must be decomposed, resumed, or partially re-run.
  • Use agora --help --all to inspect the full command tree (human-readable).
  • Use agora --help --all --json for a machine-readable command tree with all flags — the primary capability discovery mechanism for agents.
  • Use agora introspect --json when you need command labels, enums, and version metadata in a single stable artifact.
  • Use agora project doctor --json for readiness checks before continuing with automated setup.
  • Use agora whoami --plain for shell if chains that only need authenticated / unauthenticated.
  • In JSON mode, both success and failure return the same top-level envelope shape.
  • Use --json --pretty when a human needs to inspect JSON directly. Scripts should keep the default single-line JSON.
  • Use --quiet to suppress the success envelope in both pretty and JSON modes; the exit code becomes the only result. Errors are still printed on stderr (and as a JSON envelope on stdout when --json is set without --quiet). NDJSON progress events are still emitted because they are observability, not results.
  • Use --debug (equivalent to AGORA_DEBUG=1) to echo structured log records to stderr. The flag does not change exit codes, JSON envelope shape, or NDJSON progress events; it only mirrors the entries that would normally be written to the log file. Pair with --json for fully machine-parseable runs that also surface internal events to your CI logs. v0.2.0 dropped the legacy --verbose / -v alias and the AGORA_VERBOSE env var; persisted configs that contain a verbose key are auto-promoted to debug on first load.
  • Use --yes (or -y) / AGORA_NO_INPUT=1 to assume the default answer to confirmation prompts. Following industry convention for -y (apt-style), the flag never starts brand-new interactive flows: in JSON, CI, or non-TTY contexts the CLI still fails fast with the same AUTH_UNAUTHENTICATED error you would have seen without --yes, instead of silently launching an OAuth browser flow.
  • Interactive login prompts only appear in interactive pretty-mode TTY runs. Automation should authenticate up front with agora login; --json, AGORA_OUTPUT=json, detected CI environments, and non-TTY stdin all skip the prompt and fail with AUTH_UNAUTHENTICATED.
  • In non-interactive runs (--yes, JSON, CI, non-TTY), pass --template explicitly to agora init. The CLI now fails fast with QUICKSTART_TEMPLATE_REQUIRED instead of silently selecting a template.
  • Output mode precedence is: explicit CLI flag (--json or --output) first, user-set AGORA_OUTPUT second, then user-customized config file value, then CI auto-detect → JSON (see below), then pretty.
  • Set AGORA_AGENT=<tool-name> in automated environments to explicitly label agent traffic in the API User-Agent. When unset, the CLI may infer a coarse label such as cursor, claude-code, cline, windsurf, codex, or aider from known agent environment markers. Set AGORA_AGENT_DISABLE_INFER=1 to disable inference.
  • Use agora mcp serve to expose local Agora CLI tools to MCP-capable agents. The full surface is exposed: agora.version, agora.introspect, agora.auth.{status,logout}, agora.config.{path,get}, agora.telemetry.status, agora.upgrade.check, agora.project.{list,show,use,create,doctor,env,env_write}, agora.project.feature.{list,status,enable}, agora.project.webhook.{events,list,show,create,update,delete}, agora.quickstart.{list,create,env_write}, and agora.init. Authentication is intentionally not exposed via MCP because OAuth requires an interactive browser; run agora login once on the host first.
  • Use agora open --target docs for the human GitHub Pages docs and agora open --target docs-md for the agent-facing raw Markdown index. In CI/non-TTY runs the command defaults to URL-only output unless --browser is set. The Markdown tree is published under predictable /md/ URLs, for example /md/commands.md, /md/automation.md, and /md/error-codes.md.
  • Docs publishing reads internal-docs/pages/site.env for CLI_DOCS_* and CLI_INSTALL_* URL defaults; staging Pages builds can override those environment variables at workflow time without changing docs content. The resolved values are published as /docs.env for transparency.
  • The CLI maintains a short-lived on-disk completion cache for agora project use <TAB> under <AGORA_HOME>/cache/projects.json. The cache is only used for completions when a local unexpired session exists (session.json with a non-empty access token and a future expiresAt, when present), so Tab does not suggest stale project names after logout or local session expiry. The cache TTL is 5 minutes by default; override with AGORA_PROJECT_CACHE_TTL_SECONDS=<seconds> (set to 0 to disable). Cache files older than 24 h are pruned at every CLI startup. Set AGORA_DISABLE_CACHE=1 to drop the cache on the next startup. The cache is invalidated automatically by agora logout and agora project create (the latter clears the file; it does not embed the new project until the next successful list fetch). To force-refresh the cached completion page, run agora project list --refresh-cache while authenticated; that command fetches the unfiltered first page used by completion and rewrites projects.json when it succeeds.

CI auto-detect

When the CLI detects it is running inside a CI environment, it automatically:

  • Switches the default output mode to --output json (so build logs stay machine-parseable).
  • Suppresses the first-run "Config initialized" banner on stderr.
  • Skips interactive prompts (login confirmation, project reuse confirmation, template picker).

CI is detected when any of the following environment variables is present (and CI is not literally false/0/empty):

Variable Vendor
CI de-facto universal
GITHUB_ACTIONS GitHub Actions
GITLAB_CI GitLab CI
BUILDKITE Buildkite
CIRCLECI CircleCI
JENKINS_URL Jenkins
TF_BUILD Azure Pipelines

You can always override:

  • --output pretty — force pretty output even in CI.
  • AGORA_OUTPUT=pretty — same, via env (user-set values always win over auto-detect).
  • AGORA_DISABLE_CI_DETECT=1 — disable CI detection entirely (useful when iterating on a CI script locally).

Primary command groups:

  • init
  • quickstart
  • project
  • auth
  • config

Project Resolution Precedence

Commands that require a project resolve context in this order:

  1. explicit --project or positional project argument
  2. repo-local .agora/project.json from the target repo path
  3. global CLI context selected by agora project use

Agent guidance:

  • prefer explicit --project for deterministic cross-repo operations
  • rely on repo-local binding when operating repeatedly inside one bound quickstart
  • keep metadataPath from command results if you need to validate or audit project bindings

Config Isolation

The CLI creates or migrates its config directory on startup. In CI, tests, and multi-agent runs, isolate config and session state with AGORA_HOME so concurrent jobs do not mutate a shared developer profile:

export AGORA_HOME="$(mktemp -d)"
agora auth status --json
agora init my-nextjs-demo --template nextjs --project my-project --json

AGORA_HOME points directly at the Agora CLI config directory. XDG_CONFIG_HOME is also supported, but AGORA_HOME is the most explicit option for short-lived automation.

JSON Envelope

Commands that support structured output return a JSON envelope in this shape:

{
  "ok": true,
  "command": "init",
  "data": {},
  "meta": {
    "outputMode": "json",
    "exitCode": 0
  }
}

Stable top-level fields:

  • ok true for success and false for failure.
  • command Stable command label used by the CLI for the result payload.
  • data Command-specific result payload. This is usually null on failure. project doctor --json keeps its diagnostic payload on readiness failures so agents can inspect blocking issues while still branching on ok: false.
  • error Present on failure with a stable error object. Known structured failures may include error.code, error.httpStatus, and error.requestId in addition to error.message.
  • meta.outputMode Currently json when --json is used.
  • meta.exitCode Process exit code for this result. Success envelopes use 0; error envelopes use the nonzero process exit code.

Agent guidance:

  • branch on command and data
  • branch on ok first for success vs failure
  • treat pretty output as human-only
  • do not parse stderr when --json is in use

A JSON Schema for this envelope is published at docs/schema/envelope.v1.json (also available at the live URL https://agoraio.github.io/cli/schema/envelope.v1.json). Wrappers that want compile-time type safety can generate types from the schema with quicktype, datamodel-code-generator, or any JSON-Schema-aware tool.

Envelope Versioning

The current contract is envelope.v1.json. Minor CLI releases may add fields to envelopes, progress events, command result data, and introspection records. Agents must ignore unknown fields.

Breaking envelope changes require a new schema file such as envelope.v2.json, a CHANGELOG.md entry, and a migration note in this document. Removing fields, changing field types, or changing the meaning of existing enum values is treated as breaking.

One documented exception: agora project env

agora project env is the only command whose default (non-JSON) output is raw stdout — without the unified envelope — so it can be used with shell substitution:

source <(agora project env --shell)
eval "$(agora project env --format shell)"

To explicitly request a specific format, pass --format:

Flag Output
--format dotenv KEY=value lines (default; >> .env)
--format shell shell export KEY=value statements
--format envelope unified JSON envelope (alias of --json)
--format json same as --format envelope
--shell back-compat alias of --format shell
--json unified JSON envelope

For automation, prefer --json (or --format envelope) so the result has the same shape as every other command. agora project env write already emits the unified envelope under all output modes — only the read path has the raw-stdout exception above.

In interactive pretty TTY sessions, running agora project env without an explicit --format, --shell, or --json prints a stderr hint pointing agents to --json / --format envelope. The hint is not emitted in JSON mode or non-TTY automation.

Progress Events (NDJSON Stream)

Long-running commands emit one or more progress events to stdout ahead of the final envelope when --json is set. The wire format is NDJSON (newline-delimited JSON): one complete JSON object per line, terminated by \n.

Agents must therefore parse stdout line-by-line, not as a single JSON document. The terminal envelope is always the last line and is the only object with the top-level ok field.

Event shape

{"event":"progress","command":"init","stage":"clone:start","message":"Cloning quickstart repository","timestamp":"2026-04-29T22:30:00.123Z","repoUrl":"https://github.com/AgoraIO/...","targetPath":"/abs/path","ref":""}

Stable top-level fields on every progress event:

  • event — always the literal string "progress". Use this to distinguish progress events from the terminal envelope (which has "ok" instead).
  • command — the same stable command label used by the terminal envelope.
  • stage — a stable enum-like string identifying the milestone. See the table below.
  • message — short human-readable description suitable for a log line.
  • timestamp — RFC3339Nano UTC timestamp.

Additional stage-specific fields may appear (for example repoUrl, projectId, loginUrl). These are documented per-stage but agents should treat unknown extra fields as opaque metadata.

Stable stage taxonomy

Stage Emitted by When Stage-specific fields
clone:override quickstart create, init Before clone:start when an AGORA_QUICKSTART_<TEMPLATE>_REPO_URL override is in use repoUrl, envVar
clone:start quickstart create, init Before the git clone shell-out repoUrl, targetPath, ref
clone:complete quickstart create, init After git clone succeeds targetPath
clone:strip-git quickstart create, init After upstream .git metadata is removed from the scaffold targetPath
project:create init Before creating a new Agora project projectName, features
project:created init After the project is ready projectId, projectName
project:reuse init When binding to an existing project projectId, projectName
oauth:waiting login, auth login After the localhost callback server is listening and the URL is printed loginUrl, redirectUri, timeoutMs
oauth:received login, auth login When the browser callback delivers an authorization code (none)
oauth:complete login, auth login After the access token is stored locally (none)

Sample stream (init)

{"event":"progress","command":"init","stage":"project:reuse","message":"Reusing existing Agora project","timestamp":"...","projectId":"prj_abc","projectName":"Default Project"}
{"event":"progress","command":"init","stage":"clone:start","message":"Cloning quickstart repository","timestamp":"...","repoUrl":"...","targetPath":"...","ref":""}
{"event":"progress","command":"init","stage":"clone:complete","message":"Quickstart repository cloned","timestamp":"...","targetPath":"..."}
{"event":"progress","command":"init","stage":"clone:strip-git","message":"Removed quickstart repository history","timestamp":"...","targetPath":"..."}
{"ok":true,"command":"init","data":{},"meta":{"exitCode":0,"outputMode":"json"}}

Parsing rules for agents

  1. Read stdout line by line until EOF.
  2. JSON-decode each line independently.
  3. Discard or log lines that do not parse as JSON (defensive).
  4. The line where event === "progress" is a progress event; stage and message are the most useful fields.
  5. The first (and only) line where ok is set is the terminal envelope.
  6. Process exit code is also reported in meta.exitCode of the terminal envelope; treat the OS exit code as the source of truth.

Stages are stable identifiers; new stages may be added over time. Agents should treat unknown stages as benign progress information rather than failing on them.

MCP Progress Notifications

When long-running tools are invoked through MCP with _meta.progressToken, agora mcp serve forwards stage updates as JSON-RPC notifications/progress frames before the final tools/call response. This keeps stdio framing valid while allowing host agents to display progress.

Example tools/call params:

{
  "name": "agora.quickstart.create",
  "arguments": {
    "template": "nextjs",
    "dir": "my-demo"
  },
  "_meta": {
    "progressToken": "demo-1"
  }
}

Example progress notification:

{"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":"demo-1","progress":1,"stage":"clone:start","message":"Cloning quickstart repository","timestamp":"..."}}

The final MCP tool result is unchanged: the CLI result payload is JSON-stringified into content[0].text.

Implications for agent authors:

  • Use _meta.progressToken when calling agora.init, agora.quickstart.create, or agora.project.create and your host can display progress notifications.
  • Without a progress token, MCP calls remain a single final response.
  • Plan for higher tail latency on MCP tools/call for the affected tools; the user-visible "nothing is happening" gap may be tens of seconds for git clones or project creation. Consider surfacing your own "running tool: agora.init…" UI in the host agent.
  • The terminal payload shape returned in content[0].text is identical to the CLI's terminal data envelope, so existing JSON-shape handlers continue to work unchanged.
  • Shell commands (agora ... --json) still use NDJSON progress events followed by the terminal envelope.

Failure example:

{
  "ok": false,
  "command": "project env write",
  "data": null,
  "error": {
    "message": "path/to/.env.custom already exists. Use --append to append it or --overwrite to replace it.",
    "logFilePath": "/path/to/agora-cli.log"
  },
  "meta": {
    "outputMode": "json",
    "exitCode": 1
  }
}

Exit Codes

Code Meaning Commands
0 Success all commands
1 General error or blocking issue most commands; project doctor when blocking issues found
2 Non-blocking warning project doctor when only warnings found
3 Auth or session error project doctor when not authenticated; auth status / whoami when unauthenticated

In JSON mode the meta.exitCode field carries the same value as the process exit code.

Known error.code values are cataloged in error-codes.md.

Stable Result Shapes

The following commands are part of the documented JSON contract.

introspect

Example:

./agora introspect --json

Required data fields:

  • commands Array of enumerable command metadata.
  • globalFlags Root flags inherited by commands.
  • pseudoCommands Stable command labels emitted by root flags such as agora --upgrade-check.
  • enums Known enum values for agent validation.
  • version Build metadata.

Each commands[] item includes path, command, short, flags, headlessSafe, and interactivity. Agents should use headlessSafe=false to avoid flows that require direct user interaction, and use interactivity for a human-readable reason such as interactive-browser, stdio-server, or browser-in-interactive-pretty-mode.

init

Example:

./agora init my-nextjs-demo --template nextjs --json
./agora init my-nextjs-demo --template nextjs --new-project --json

By default init reuses an existing project — preferring one named exactly "Default Project". If no default exists, interactive sessions show existing projects with a create-new option and default to the most recently created project; JSON, CI, and non-TTY runs select the most recent project automatically. Pass --new-project to force creation. Use --project <name|id> to bind to a specific project. For deterministic automation, always pass --project <name|id> or --new-project.

Required data fields:

  • action Always init.
  • template Template ID such as nextjs, python, or go.
  • projectAction created or existing.
  • reusedExistingProject Boolean mirror for agents that branch on init reuse.
  • projectId
  • projectName
  • projectSelectionReason One of explicit_project, new_project, no_existing_projects, default_name, interactive_new_project, interactive_selection, or most_recent.
  • region
  • path Absolute path to the cloned quickstart.
  • envPath Path of the env file relative to the cloned quickstart root.
  • metadataPath Repo-local project binding file path, currently .agora/project.json.
  • enabledFeatures Array of features enabled during this run. Defaults to rtc, rtm, and convoai for newly created projects unless overridden with --feature. Empty for existing projects since the CLI did not create them in this run.
  • nextSteps Ordered list of suggested follow-up commands for the selected template.
  • status Currently ready.

Optional fields:

  • rtmDataCenter RTM data center configured on the new project when RTM was enabled. Defaults to NA when --rtm-data-center is omitted.

Display-oriented fields:

  • title

Safe branch fields:

  • template
  • projectAction
  • projectId
  • path
  • envPath
  • status

project create

Automation notes:

  • --dry-run returns the planned envelope (status: "planned", dryRun: true) without creating remote resources.
  • --idempotency-key <key> is forwarded to the API body for retry-safe project creation where supported.

Example:

./agora project create my-agent-demo --json
./agora project create my-agent-demo --rtm-data-center EU --json
./agora project create my-agent-demo --feature rtc --feature convoai --json

Required data fields (success):

  • action Always create.
  • projectId
  • projectName
  • appId
  • region
  • enabledFeatures Array of features that were enabled on the new project. Defaults to ["rtc", "rtm", "convoai"] when no --feature flags are passed. Explicit convoai requests also include rtm.

Optional fields:

  • rtmDataCenter RTM data center configured when RTM was enabled. Defaults to NA when --rtm-data-center is omitted.

Required data fields (--dry-run):

  • action Always create.
  • dryRun Always true.
  • status Always planned.
  • projectName
  • region
  • enabledFeatures
  • template Project preset that would be applied (empty when not requested).
  • idempotencyKey Echoes the caller-provided --idempotency-key value (empty when not provided).

Optional fields (--dry-run):

  • rtmDataCenter Uppercased data center value (CN, NA, EU, or AP) when RTM is enabled. Defaults to NA when omitted.

Safe branch fields:

  • projectId (success only)
  • projectName
  • region
  • enabledFeatures
  • status (--dry-run only)
  • dryRun (--dry-run only)

project use

Example:

./agora project use my-agent-demo --json

Required data fields:

  • action Always use.
  • projectId
  • projectName
  • region
  • status Currently selected.

Safe branch fields:

  • projectId
  • projectName
  • region
  • status

project show

Example:

./agora project show --json

Required data fields:

  • action Always show.
  • projectId
  • projectName
  • appId
  • region
  • tokenEnabled

Optional fields:

  • appCertificate The app certificate (signing key). Present when the project has one configured. Sensitive — redacted in pretty output; available in JSON mode.

Display-oriented fields:

  • appCertificate

Safe branch fields:

  • projectId
  • projectName
  • appId
  • region
  • tokenEnabled

project env write

Example:

./agora project env write apps/web/.env.local --json

Optional data fields:

  • credentialLayout Either standard (AGORA_* keys) or nextjs (NEXT_PUBLIC_AGORA_APP_ID and NEXT_AGORA_APP_CERTIFICATE) when the workspace is detected or overridden as Next.js.

Required data fields:

  • action Always env-write.
  • projectId
  • projectName
  • path Absolute path to the written dotenv file.
  • projectType Detected workspace type used for future repo metadata (nextjs, go, python, node, or standard).
  • status One of created, updated, appended, or overwritten.
  • keysWritten Ordered list of credential keys that were written. By default project env write uses AGORA_APP_ID and AGORA_APP_CERTIFICATE. Next.js workspaces (detected via package.json / next.config.* / env.local.example / repo .agora projectType / template: nextjs, or forced with --template nextjs) use NEXT_PUBLIC_AGORA_APP_ID and NEXT_AGORA_APP_CERTIFICATE instead. Non-secret project metadata stays in .agora/project.json.

Optional data fields (present when the CLI updates or creates repo metadata):

  • metadataUpdated true when .agora/project.json was created or updated for the selected project (including projectType and envPath when missing).
  • metadataPath Relative path .agora/project.json from the repo root when metadataUpdated is true.

Pass --template standard to force AGORA_* keys when auto-detection would pick Next.js.

Write behavior:

  • existing .env and .env.local files are preserved; missing credential keys are appended and existing credential keys are updated
  • existing legacy Agora-managed blocks are replaced with plain credential assignments
  • duplicate credential assignments are commented out after the first updated key
  • explicit non-standard env files still require --append or --overwrite when they do not already contain managed credentials

Safe branch fields:

  • path
  • status
  • keysWritten
  • credentialLayout
  • projectType
  • metadataUpdated (when repo binding was updated)
  • metadataPath (when metadataUpdated is true)

project env

Example:

./agora project env --json

Required data fields:

  • action Always env.
  • format Currently json.
  • projectId
  • projectName
  • region
  • values Object containing the rendered env key/value pairs.

Safe branch fields:

  • projectId
  • projectName
  • region
  • values

quickstart list

Example:

./agora quickstart list --json

Required data fields:

  • action Always list.
  • items Array of template objects.

Each item currently includes:

  • id
  • title
  • description
  • runtime
  • repoUrl
  • docsUrl
  • available
  • envDocs
  • supportsInit

Safe branch fields:

  • items[].id
  • items[].runtime
  • items[].repoUrl
  • items[].available
  • items[].supportsInit

Display-oriented fields:

  • title
  • description
  • docsUrl
  • envDocs

quickstart create

Automation notes:

  • --ref <branch|tag|ref> pins the cloned quickstart source for workshops and reproducible demos.

Example:

./agora quickstart create my-python-demo --template python --project my-project --json

Required data fields:

  • action Always create.
  • template
  • title
  • runtime
  • cloneUrl
  • docsUrl
  • path Absolute path to the cloned quickstart.
  • envStatus template-only or configured.
  • envPath Empty when no project was bound during creation.
  • metadataPath .agora/project.json when the quickstart was bound to a project during creation.
  • status Currently cloned.
  • written Files or managed outputs written by the command.

Optional fields:

  • projectId
  • projectName

Safe branch fields:

  • template
  • path
  • envStatus
  • envPath
  • status
  • projectId

quickstart env write

Example:

./agora quickstart env write /abs/path/to/my-python-demo --json

Required data fields:

  • action Always env-write.
  • template
  • title
  • path Absolute path to the quickstart root.
  • envPath Env file path relative to the quickstart root.
  • metadataPath Repo-local project binding file path, currently .agora/project.json.
  • projectId
  • projectName
  • status Currently created, updated, or appended.

Env write behavior:

  • quickstart env files contain only the App ID and App Certificate variable names required by the template
  • Next.js uses NEXT_PUBLIC_AGORA_APP_ID and NEXT_AGORA_APP_CERTIFICATE
  • Python and Go use APP_ID and APP_CERTIFICATE
  • project metadata such as project ID, project name, region, template, projectType, and env path is stored in .agora/project.json
  • existing quickstart env files are preserved; missing credential keys are appended and existing credential keys are updated
  • stale Agora credential aliases for another runtime are commented out to avoid ambiguous dotenv resolution; for example, a Next.js quickstart prefers NEXT_PUBLIC_AGORA_APP_ID and comments out old AGORA_APP_ID / APP_ID entries when replacing them

Safe branch fields:

  • template
  • path
  • envPath
  • projectId
  • projectName
  • status

project doctor

Example:

./agora project doctor --json

Required data fields:

  • action Always doctor.
  • healthy
  • mode default or deep.
  • status One of healthy, warning, not_ready, or auth_error.
  • summary
  • checks Array of category objects.
  • blockingIssues Array of blocking issue objects.
  • warnings Array of warning issue objects.

Optional fields:

  • project Nil during auth or project-selection failure paths.
  • workspace Present in deep mode with repo-local binding and env consistency details.

Safe branch fields:

  • healthy
  • mode
  • status
  • summary
  • blockingIssues
  • warnings

Recommended agent behavior:

  • branch first on status
  • use healthy as a fast readiness boolean
  • inspect blockingIssues[].suggestedCommand for recovery suggestions
  • for repo-bound validation, run project doctor --deep --json

auth status

Examples:

./agora auth status --json
./agora whoami --json

When authenticated, this command returns a success envelope with these required data fields:

  • action Always status.
  • authenticated
  • status authenticated.
  • region
  • expiresAt
  • scope

Safe branch fields:

  • authenticated
  • region
  • status
  • expiresAt

When unauthenticated, this command returns exit code 3 and an error envelope:

{
  "ok": false,
  "command": "auth status",
  "data": null,
  "error": {
    "message": "No local Agora session found. Run `agora login` first.",
    "code": "AUTH_UNAUTHENTICATED",
    "logFilePath": "/path/to/agora-cli.log"
  },
  "meta": {
    "outputMode": "json",
    "exitCode": 3
  }
}

Agent guidance:

  • branch on ok before reading data
  • handle error.code == "AUTH_UNAUTHENTICATED" as the unauthenticated state
  • run agora login before continuing with commands that require a session

auth login

Example:

./agora login --json
./agora auth login --json

login --json is an NDJSON stream, not a single JSON blob: it emits oauth:waiting, oauth:received, and oauth:complete progress events before the final envelope. Parse stdout line-by-line and use the last object with top-level ok as the command result.

Required data fields:

  • action Always login.
  • status Currently authenticated.
  • region
  • scope
  • expiresAt

Safe branch fields:

  • region
  • status
  • expiresAt

auth logout

Example:

./agora logout --json
./agora auth logout --json

Required data fields:

  • action Always logout.
  • status Currently logged-out.
  • clearedSession true if a session file was removed; false if no session existed.

Safe branch fields:

  • status
  • clearedSession

project list

Example:

./agora project list --json
./agora project list --keyword demo --page 2 --json
./agora project list --refresh-cache --json

Required data fields:

  • items Array of project summary objects.
  • page Current page number (1-based).
  • pageSize Number of items per page.
  • total Total number of matching projects across all pages.
  • cacheRefreshed Boolean. true only when --refresh-cache successfully refreshed the unfiltered first-page project completion cache.

Each item includes: projectId, name, appId, projectType, status, createdAt, updatedAt.

Safe branch fields:

  • items[].projectId
  • items[].name
  • total
  • page
  • pageSize

project feature list

Example:

./agora project feature list --json
./agora project feature list my-project --json

Required data fields:

  • action Always feature-list.
  • projectId
  • projectName
  • items Array of feature status objects.

Each item includes: feature (one of rtc, rtm, convoai), status (one of enabled, disabled, included, provisioning), message.

Safe branch fields:

  • projectId
  • items[].feature
  • items[].status

project feature status

Example:

./agora project feature status convoai --json

Required data fields:

  • action Always feature-status.
  • feature
  • status One of enabled, disabled, included, provisioning.
  • message
  • projectId
  • projectName

Safe branch fields:

  • feature
  • status
  • projectId

project feature enable

Example:

./agora project feature enable convoai --json

Required data fields:

  • action Always feature-enable.
  • feature
  • status One of enabled, included.
  • message
  • projectId
  • projectName

Safe branch fields:

  • feature
  • status
  • projectId

project webhook

Examples:

./agora project webhook events --feature rtc --json
./agora project webhook create --project my-project --feature rtc --url https://example.com/webhook --events channel-created,user-joined --json
./agora project webhook show 42 --project my-project --feature rtc --with-secret --json
./agora project webhook update 42 --project my-project --feature rtc --url https://example.com/webhook2 --json
./agora project webhook delete 42 --project my-project --feature rtc --yes --json

Webhook commands are feature-scoped. Pass --feature rtc, --feature rtm, or --feature convoai and prefer explicit --project <id|name> for automation.

Run project webhook events --feature <feature> --json before creating a webhook to discover the event IDs and keys that can be passed to --events.

project webhook events required data fields:

  • action Always webhook-events.
  • feature
  • items Array of event objects.

Each event item includes:

  • id
  • key Stable CLI event key derived from the English display name, for example channel-created.
  • displayName
  • eventType
  • payload when provided by the API.

project webhook list required data fields:

  • action Always webhook-list.
  • projectId
  • projectName
  • feature
  • events The available event catalog for the selected feature.
  • items Array of webhook config objects.

Each list item includes:

  • configId
  • url
  • urlRegion Delivery region for webhook callbacks: cn, sea, na, or eu.
  • enabled Canonical webhook state field. Webhook JSON does not emit a string status.
  • eventIds
  • events Event details that match eventIds when available.
  • retry Retry behavior when returned by the API. This field is read-only in the CLI.
  • useIpWhitelist
  • secret Present when the backend returns a secret, redacted as ********. list never emits a raw secret.

project webhook show, project webhook create, and project webhook update required data fields:

  • action One of webhook-show, webhook-create, or webhook-update.
  • projectId
  • projectName
  • feature
  • configId
  • url
  • urlRegion Delivery region for webhook callbacks: cn, sea, na, or eu.
  • enabled Canonical webhook state field. Webhook JSON does not emit a string status.
  • eventIds
  • events Event details that match eventIds when available.
  • useIpWhitelist
  • config Nested webhook config object with the same config fields.

Optional top-level data fields for show, create, and update (also present in the nested config object when set):

  • secret Webhook signing secret. create returns the generated or caller-provided secret at data.secret and data.config.secret so automation can store it. show returns the raw secret only with --with-secret; otherwise it redacts data.secret and data.config.secret as ********. update does not rotate secrets; when the backend returns a secret, update emits the redacted value. list has no top-level secret; item secrets are redacted as items[].secret == "********".
  • retry Retry behavior when returned by the API. This field is read-only in the CLI and appears at data.retry and data.config.retry; list exposes it per item as items[].retry.

project webhook create requires --events <event-id-or-key>[,<event-id-or-key>...]. project webhook update preserves existing values for omitted mutable fields. Use --url, --events, --delivery-region, --enabled, or --disabled to replace only those fields. update does not rotate or emit the raw secret.

project webhook delete required data fields:

  • action Always webhook-delete.
  • projectId
  • projectName
  • feature
  • configId
  • deleted true after the remote config is deleted.

Delete is destructive and requires confirmation. Pass --yes (or -y) in CLI automation; the MCP delete tool requires confirm: true.

Safe branch fields by command shape:

  • Event discovery: feature, items[].id, items[].key
  • List: projectId, feature, items[].configId, items[].enabled, items[].eventIds, items[].urlRegion
  • Show/create/update: projectId, feature, configId, enabled, eventIds, urlRegion
  • Delete: projectId, feature, configId, deleted

config path

Example:

./agora config path --json

Required data fields:

  • path Absolute path to the config file on disk.

Safe branch fields:

  • path

config get

Example:

./agora config get --json

Returns the current resolved config object. Safe branch fields:

  • output
  • logLevel
  • browserAutoOpen
  • telemetryEnabled
  • debug (renamed from legacy verbose in v0.2.0; legacy key is migrated on first load)

Endpoint and OAuth integration values are derived from the active login region and may be temporarily overridden with environment variables such as AGORA_API_BASE_URL, AGORA_OAUTH_BASE_URL, AGORA_OAUTH_CLIENT_ID, and AGORA_OAUTH_SCOPE; they are not persisted in config.json.

Migration note: configs written by older CLI versions may contain apiBaseUrl, oauthBaseUrl, oauthClientId, or oauthScope. Schema version 4 drops those keys on first load. If automation previously depended on those persisted values, set the corresponding AGORA_* environment variable in the job environment instead.

config update

Example:

./agora config update --output json --json
./agora config update --telemetry-enabled=false --json

Boolean config flags use Cobra's explicit false syntax. To disable a boolean, pass --flag=false (for example --telemetry-enabled=false, --browser-auto-open=false, or --debug=false); omitting the flag leaves the persisted value unchanged.

Returns the updated config object with the same shape as config get. Safe branch fields are the same as config get.

upgrade

Example:

./agora upgrade --json
./agora upgrade --check --json
./agora --upgrade-check --json

CI/agent guidance: prefer --check (or --upgrade-check) so automation does not mutate the running binary.

Required data fields:

  • action upgrade for the subcommand and upgrade-check for the root --upgrade-check pseudo-command.
  • installMethod One of installer, npm, homebrew, scoop, chocolatey, winget, or unknown.
  • installSource install.sh / install.ps1 when read from a valid direct-installer receipt, path when inferred from the resolved executable path, or fallback when no durable source was available.
  • installedPath Resolved executable path used for receipt validation and path inference.
  • upgradeCommand The user-facing command for the owning install channel.
  • command Backwards-compatible alias for upgradeCommand.
  • status One of manual, dry-run, up-to-date, or upgraded.

Optional fields:

  • receiptPath Path to the validated agora.install.json receipt when present.
  • currentVersion Version of the running binary for agora upgrade.
  • latestVersion Latest resolved release version when the command resolves GitHub release metadata.
  • version Structured version payload for agora --upgrade-check.
  • receiptWarning Nonfatal warning when a direct-installer self-update succeeded but the CLI could not refresh agora.install.json.
  • ciBlocked Present and true when installer-managed self-update is skipped because CI auto-detect is active and AGORA_ALLOW_UPGRADE_IN_CI is not set.
  • suggestedCommand Suggested non-mutating check command when ciBlocked is true.

Upgrade behavior:

  • direct-installer installs (installMethod: "installer") self-update in place after downloading the GitHub release archive and verifying it against checksums.txt
  • archive prefix is version-aware: agora-cli-go_* for target releases v0.1.7–v0.2.0, agora-cli_* for v0.2.1+
  • in CI, installer-managed self-update is skipped by default (status: "manual" + ciBlocked: true); set AGORA_ALLOW_UPGRADE_IN_CI=1 to opt in
  • package-manager installs return status: "manual" with the owning package-manager command; agents should run that command only after user approval
  • unknown means the CLI could not verify the install channel, usually because the binary is a development/test build

Safe branch fields:

  • installMethod
  • installSource
  • upgradeCommand
  • status

Human vs Machine Output

  • Pretty output is optimized for humans.
  • JSON output is the supported machine-readable contract.
  • For reliable automation, do not parse help text or pretty output.
  • Use --output pretty to force human output when AGORA_OUTPUT=json is set in the environment.

Recommended pattern:

./agora project doctor --json
./agora init my-go-demo --template go --json
./agora quickstart env write my-go-demo --json