Agora CLI

Native Agora CLI for authentication, project management, quickstart setup, and developer onboarding. Use it to go from an Agora account to a runnable app with one command.

Install

Requirements

macOS 12+, Linux (glibc 2.31+ or musl), or Windows 10+ for the prebuilt binaries.
git on PATH for agora init and agora quickstart create (they shell out to git clone).
PowerShell 7+ (pwsh) for the native Windows installer.
For the source build, the Go toolchain pinned in go.mod.

Install the CLI

curl -fsSL https://dl.agora.io/cli/install.sh | sh

Run the CLI:

agora --help

The script is served from the Agora CDN (dl.agora.io, CloudFront). Binaries download from GitHub by default and automatically fall back to the CDN mirror if GitHub is unreachable; downloads are verified against checksums.txt regardless of source.

Windows PowerShell 7+:

irm https://dl.agora.io/cli/install.ps1 | iex

If execution policy blocks the installer, download it to disk and launch it in a new PowerShell 7 process with a process-scoped bypass:

Invoke-WebRequest -Uri https://dl.agora.io/cli/install.ps1 -OutFile .\install.ps1
pwsh -NoProfile -ExecutionPolicy Bypass -File .\install.ps1

An organization-level MachinePolicy or UserPolicy can override the process setting. In that case, ask an administrator to allow the script or use a verified release archive instead.

Alternative install paths (GitHub-hosted; use install.ps1 for PowerShell):

# GitHub Pages
curl -fsSL https://agoraio.github.io/cli/install.sh | sh
# raw GitHub
curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh

Locked-down environments that block curl | sh can download a release archive from GitHub or mirror the binary internally. Every release includes checksums.txt, a Cosign keyless signature, and an SBOM; see docs/install.md for manual tarball, checksum, and Cosign verification steps. The npm distribution is currently paused; the package on npm may be stale and should not be used.

Notes:

The shell installer supports macOS, Linux, and Windows POSIX shells such as Git Bash. Use install.ps1 for native PowerShell installs on Windows.
Shell setup is auto-on: the installer wires the install directory onto your PATH (when needed) and writes a shell completion script for the detected shell (bash, zsh, fish, or PowerShell). Pass --no-path, --no-completion, or the umbrella --skip-shell (PowerShell: -NoPath / -NoCompletion / -SkipShell) to opt out granularly.
Installer help is always available with curl -fsSL https://dl.agora.io/cli/install.sh | sh -s -- --help.
Pinned versions, dry runs, custom install directories, and source builds are documented in docs/install.md.
Release artifacts and checksums: GitHub Releases. Vulnerability disclosures: SECURITY.md.

Restricted networks (GitHub blocked)

The default command already fetches the install script from the Agora CDN (dl.agora.io), so it works even where GitHub is blocked. Binaries still download from GitHub first (with automatic fallback to the mirror); in a fully-blocked region, add AGORA_INSTALL_SOURCE=s3 to skip GitHub entirely and avoid the failover delay:

# macOS, Linux, and Windows POSIX shells
curl -fsSL https://dl.agora.io/cli/install.sh | AGORA_INSTALL_SOURCE=s3 sh

# Windows PowerShell
$env:AGORA_INSTALL_SOURCE = 's3'; irm https://dl.agora.io/cli/install.ps1 | iex

Downloads are still SHA-256 verified against checksums.txt regardless of source. AGORA_INSTALL_SOURCE accepts auto (default; GitHub then mirror), github, or s3. See docs/install.md for details.

Build from source

go build -o agora .
./agora --help

Requires the Go toolchain pinned in go.mod. For direct installer options and source install notes, see docs/install.md.

Quick Start

Recommended path: install the CLI, log in, then run agora init. The CLI binds a project, clones an official quickstart or recipe, writes the runtime env file (App ID and App Certificate), and creates .agora/project.json. You do not need to download an env file from Agora Console for this flow.

# 1) Log in
agora login

# 2) Create a local demo bound to a project
# Interactive (TTY): reuses "Default Project" if present; otherwise prompts to pick or create
agora init my-nextjs-demo --template nextjs
# Or initialize an official recipe from recipes.agora.io
# agora init my-agent --recipe tool-calling
# For deterministic non-interactive / --json / CI runs, select or create explicitly
# agora init my-nextjs-demo --template nextjs --project <project-id-or-name>
# agora init my-nextjs-demo --template nextjs --new-project

# 3) Install deps and start the app (follow nextSteps from init; Next.js example:)
cd my-nextjs-demo
pnpm install
# Newer pnpm may block dependency build scripts (ERR_PNPM_IGNORED_BUILDS). If so:
# pnpm approve-builds --all
# pnpm rebuild
pnpm dev
# Other templates print their own commands, e.g. python: bun run setup && bun run dev
# go: make setup && make dev

# 4) Open the app in a browser (Next.js default: http://localhost:3000)
open http://localhost:3000
# Linux: xdg-open http://localhost:3000
# Windows: start http://localhost:3000

# 5) Optional: check project/workspace readiness
agora project doctor --json

init also prints template-specific next steps in its output. Refresh credentials or rebind the repo later with:

cd my-nextjs-demo
agora quickstart env write . --project <project-id-or-name>

If an env or project command reports No project selected, pass --project, run agora project use <project>, or work inside a directory that already has .agora/project.json. That is expected when none of those contexts exist—not a missing Console env download. agora init uses the onboarding selection flow described above instead.

Command examples use agora for the installed CLI. Local source builds use ./agora from the repo root.

What You Can Build Quickly

Goal	Command	What You Get
Next.js video app	`agora init my-nextjs-demo --template nextjs`	A cloned Next.js quickstart, `.agora` binding, and `.env.local`
Python voice agent	`agora init my-python-demo --template python`	A Python quickstart with `server/.env` credentials
Go voice agent	`agora init my-go-demo --template go`	A Go quickstart with `server/.env` credentials
Android voice AI app	`agora init my-android-demo --template android`	An Android client with credentials written only to the included Python server
Official recipe	`agora init my-agent --recipe tool-calling`	The recipe repository, API-defined env file, and `.agora` binding

Android follows the same project binding and env-writing flow as the web quickstarts. Its nextSteps additionally cover starting the Python server, opening a temporary HTTPS tunnel, writing that public URL to local.properties, and assembling the Android client. The App Certificate remains only in server/.env.local.

By default init reuses a project named Default Project when present. In an interactive TTY without that project, it prompts you to pick an existing project or create a new one. Non-interactive/--json/CI runs fall back to the most recent project (or create one when none exist). Pass --project <id-or-name> or --new-project to control selection explicitly. Run agora quickstart list to see all available templates.

Command Model

The command model is intentionally layered:

init for the recommended onboarding path (project + clone + env)
quickstart for local cloned starter repos (requires git)
recipes for read-only discovery of official recipes from recipes.agora.io
project for remote Agora control-plane resources (does not clone scaffolds)
auth for login and session inspection
config for local CLI defaults
telemetry for telemetry preferences
upgrade / update / self-update for in-place upgrade or package-manager-specific guidance
open to open the Console, published CLI docs (human or /md/ Markdown), or product docs in a browser
doctor for an install self-test (PATH, version, network, auth, MCP host)
env-help to list every AGORA_* environment variable the CLI honors
skills to browse curated workflow recipes for humans and AI agents
mcp to run the CLI as a local MCP server (agora mcp serve) for agent integrations
completion for shell completion scripts (auto-installed by the installer; see agora completion --help for manual setup)

Which command?

Goal	Command
New user, one shot	`agora init <name> --template <id>` or `--recipe <slug>` (reuses `Default Project` / interactive picker; or `--project` / `--new-project`)
List available templates	`agora quickstart list`
List official recipes	`agora recipes list`
Clone a starter only	`agora quickstart create ... --template-only`
Re-sync / rebind env in a cloned quickstart	`agora quickstart env write [dir]` (optional `--project` to rebind)
Write env to an arbitrary path / non-quickstart repo	`agora project env write <path>`
Set global CLI project context	`agora project use <project>`
Install self-test	`agora doctor --json`
Project/workspace readiness	`agora project doctor --json` (add `--deep` in a bound repo)
Manage feature webhooks	`agora project webhook ... --json`

Env-related commands

agora init <name>                    # recommended: project + clone + env
├── project
│   ├── env                          Print project env values (no file write)
│   └── env write <path>             Generic dotenv block (AGORA_* or NEXT_*)
└── quickstart
    └── env write [dir]              Template-specific env file and key names

Discover the full command tree:

agora --help
agora --help --all
agora introspect --json

`init`

Recommended onboarding command. By default it reuses a project named Default Project when present. In an interactive TTY without that project, it prompts you to pick or create one. Non-interactive/--json/CI runs fall back to the most recent project (or create one when none exist). Prefer --project <id-or-name> or --new-project for explicit selection. It clones either a built-in quickstart (--template) or an official catalog recipe (--recipe), writes credentials using that source's env contract, writes .agora/project.json, updates global context, and prints next steps.

`recipes`

Lists and inspects the official recipes published by recipes.agora.io. Use recipes list --type all|ai|rtc to discover slugs and recipes show <slug> to inspect the repository, recipe document, and optional CLI initialization metadata. Recipe discovery is read-only; init --recipe performs the clone.

`quickstart`

Manages standalone official starter repos and their runtime-specific env files.

Use this when you want to:

list available templates with quickstart list
clone a quickstart without creating a project
bind a quickstart to an existing project
re-sync env files after changing project selection

`project`

Manages remote Agora project resources.

Use this when you want to:

create or inspect projects directly
switch the default project context
export project env values with project env
write credentials to a dotenv file with project env write
inspect project readiness with project doctor
manage feature-scoped webhook endpoints with project webhook

`auth`

Handles login, logout, and current session inspection.

`config`

Reads and updates local CLI defaults such as output mode, log level, and browser behavior.

`telemetry`

Reads and updates telemetry preferences. DO_NOT_TRACK=1 disables telemetry at runtime.

`open`

Opens curated URLs: Console (--target console), human CLI docs on GitHub Pages (docs), raw Markdown tree for agents (docs-md), and Agora product docs (product-docs). Use --no-browser to print the resolved URL.

`mcp`

Runs the CLI as a local MCP server so MCP-capable clients can call Agora workflows as tools. Authenticate with agora login on the host first; OAuth is not exposed through MCP.

`version`

Prints build metadata. Release binaries include version, commit, and build date.

Env Files and Project Binding

Env files hold runtime credentials. Project selection is separate: use --project, .agora/project.json, or agora project use. The CLI writes App ID and App Certificate from the selected project's API response into the template env file. It does not download a ready-made dotenv from Agora Console.

Prefer agora quickstart env write inside official quickstarts. Use agora project env write <path> only when you need a specific dotenv path outside that layout.

Command	Env path	Key names
`agora init` / `quickstart env write`	Template-defined (`.env.local`, `server/.env`, or `server/.env.local`)	Template-specific (`NEXT_PUBLIC_`, `AGORA_`, …)
`agora project env write <path>`	User-supplied path	`AGORA_` or `NEXT_` only

Quickstart template behavior:

Next.js quickstarts write .env.local with NEXT_PUBLIC_AGORA_APP_ID plus NEXT_AGORA_APP_CERTIFICATE
Python quickstarts copy server/.env.example to server/.env, then use AGORA_APP_ID plus AGORA_APP_CERTIFICATE
Go quickstarts copy server/.env.example to server/.env, then use AGORA_APP_ID plus AGORA_APP_CERTIFICATE
Existing Python and Go quickstarts keep their recorded env path when reconfigured, while legacy APP_ID / APP_CERTIFICATE assignments are commented out and replaced with AGORA_APP_ID / AGORA_APP_CERTIFICATE.

project env write auto-detects Next.js workspaces (or accepts --template nextjs|standard) and writes AGORA_APP_ID / AGORA_APP_CERTIFICATE or the Next.js equivalents.

Existing .env and .env.local files are preserved: the CLI appends missing credentials, updates existing credential keys, and comments out duplicate or stale Agora credential aliases for the selected runtime.

See Using .env.local for how the CLI creates and updates env files from Quickstart examples and the selected project's credentials.

See docs/automation.md for JSON fields and the full credential matrix.

Repo-local binding

.agora/project.json is the repo-local project binding (not the env file). It lets the CLI know which Agora project a cloned demo uses when you work inside that repo later. agora project use only sets the global CLI context and does not rewrite .agora/project.json.

Commands that resolve an existing project context, including env-write commands, use this precedence:

explicit --project or positional project argument
repo-local .agora/project.json resolved from the target repo path
global CLI context from agora project use

The .agora/project.json file is created or updated by:

agora init
agora quickstart create ... --project ...
agora quickstart env write ...
agora project env write ... (fills missing projectType / envPath when applicable)

It stores durable non-secret metadata:

projectId
projectName
region
template
projectType (framework hint used for env layout when present)
envPath

Examples:

# Inside a bound quickstart repo
agora project show --json

# From any directory, target a repo path directly
agora quickstart env write /abs/path/to/my-go-demo --json

# Rebind a repo to a different project
agora quickstart env write /abs/path/to/my-go-demo --project my-other-project --json

Common Workflows

Use an existing project with a quickstart

agora quickstart create my-go-demo --template go --project my-existing-project
agora quickstart env write my-go-demo --project my-existing-project

Update env after changing projects

agora project use my-agent-demo
agora quickstart env write my-go-demo

Use low-level commands directly

agora project create my-agent-demo --feature rtc --feature convoai
agora quickstart create my-go-demo --template go --project my-agent-demo
agora quickstart env write my-go-demo --project my-agent-demo

Automation and Agents

For scripts, CI, and agentic workflows:

prefer --json for machine consumption
set AGORA_HOME to an isolated temporary directory in CI or multi-agent runs
prefer init for end-to-end setup; decompose with lower-level commands when a workflow must be resumed in stages
use agora introspect --json and AGENTS.md for agent discovery; docs/automation.md for the JSON envelope contract

Example:

export AGORA_HOME="$(mktemp -d)"
agora init my-nextjs-demo --template nextjs --json
agora quickstart create my-python-demo --template python --project my-project --json
agora quickstart env write my-python-demo --json
agora project doctor --json
agora auth status --json

auth status --json exits 3 with error.code set to AUTH_UNAUTHENTICATED when no local session exists.

Configuration

The CLI stores config, session, context, and logs under the Agora CLI config directory for the current machine.

Useful commands:

agora config path
agora config get

Built-in default config values are documented in config.example.json.

Troubleshooting

For a full troubleshooting guide with diagnostic commands, see docs/troubleshooting.md.

Start with the right doctor command:

agora doctor --json — install self-test (PATH, version, network, auth, MCP host)
agora project doctor --json — project and workspace readiness (credentials, .agora binding, env consistency; add --deep for repo-local checks)

The most common issues:

agora not found after install: the installer wires PATH automatically by default; if you ran with --no-path or --skip-shell, re-run without it (or add the install directory to your shell profile manually).
OAuth browser does not open: agora login --no-browser prints the URL so you can open it elsewhere; or agora config update --browser-auto-open=false.
git is missing: agora init and agora quickstart create shell out to git clone. Install git and retry.
Project has no app certificate: quickstart env write, init, and project env --with-secrets need a project with an App Certificate. Pick another project or enable one in Agora Console.
No project selected: the command has no project context. Pass --project <name>, run agora project use <name>, or work inside a repo with .agora/project.json (created by init / quickstart env write). Do not expect the CLI to infer a project from .env.local alone.
Wrong or stale credentials in a quickstart: re-run agora quickstart env write . --project <id> from the demo directory instead of pasting a Console-downloaded env file.

Full guide with debug logging, CI tips, completion troubleshooting, and the --debug flag: docs/troubleshooting.md.

Documentation

Human docs (GitHub Pages): https://agoraio.github.io/cli/
Agent-friendly Markdown mirror: https://agoraio.github.io/cli/md/
Release notes: CHANGELOG.md
Install options (direct installer, Windows, source): docs/install.md
Full command reference (auto-generated): docs/commands.md
Automation and JSON contract: docs/automation.md
JSON envelope schema (machine-readable): docs/schema/envelope.v1.json
Stable error codes: docs/error-codes.md
Telemetry controls: docs/telemetry.md
Troubleshooting: docs/troubleshooting.md
Security policy: SECURITY.md
Support and contact channels: SUPPORT.md
Contributor and agent guide: AGENTS.md, plus CONTRIBUTING.md

Name		Name	Last commit message	Last commit date
.github		.github
cmd/gendocs		cmd/gendocs
docs		docs
internal-docs		internal-docs
internal/cli		internal/cli
packaging		packaging
scripts		scripts
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
RELEASING.md		RELEASING.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
config.example.json		config.example.json
go.mod		go.mod
go.sum		go.sum
install.ps1		install.ps1
install.sh		install.sh
main.go		main.go

Navigation Menu

Uh oh!

Repository files navigation

Agora CLI

Install

Requirements

Install the CLI

Restricted networks (GitHub blocked)

Build from source

Quick Start

What You Can Build Quickly

Command Model

Which command?

Env-related commands

`init`

`recipes`

`quickstart`

`project`

`auth`

`config`

`telemetry`

`open`

`mcp`

`version`

Env Files and Project Binding

Repo-local binding

Common Workflows

Use an existing project with a quickstart

Update env after changing projects

Use low-level commands directly

Automation and Agents

Configuration

Troubleshooting

Documentation

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Agora CLI

Install

Requirements

Install the CLI

Restricted networks (GitHub blocked)

Build from source

Quick Start

What You Can Build Quickly

Command Model

Which command?

Env-related commands

init

recipes

quickstart

project

auth

config

telemetry

open

mcp

version

Env Files and Project Binding

Repo-local binding

Common Workflows

Use an existing project with a quickstart

Update env after changing projects

Use low-level commands directly

Automation and Agents

Configuration

Troubleshooting

Documentation

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`init`

`recipes`

`quickstart`

`project`

`auth`

`config`

`telemetry`

`open`

`mcp`

`version`