CLI reference

The Standard Agents CLI is the @standardagents/cli package. Its command is agents. You do not need to install it:

npx @standardagents/cli@latest <command>

Inside a project that has the package installed, pnpm exec agents <command> or npx agents <command> runs the same program. The examples on this page write agents <command> for both forms.

The CLI supports Node.js 22 (22.12 or newer) and Node.js 24. An older Node.js stops with the version to install. An untested release line above Node.js 22 prints a warning and continues. git-credential skips the version check.

agents --help lists the commands, and agents <command> --help lists the flags of one command. agents --version prints the CLI version. In a terminal, agents with no command opens the home screen of the full-screen app. Without a terminal, it prints the help text on the error stream and exits with code 1.

Full-screen app

On an interactive terminal, agents with no command, agents init, and agents login run as one full-screen app. The app uses the alternate screen of the terminal, so your scrollback is unchanged while it runs.

• The top bar shows the CLI version, the signed-in account, and the current directory.
• The body shows the steps of the run with their state, and one main region for the active step: the sign-in URL, the output of the clone and the install, or the log of the dev server.
• The bottom bar shows what happens now, the elapsed or remaining time, and the keys that work.

The home screen lists the commands that work in the current directory. For each one it shows what the command does and the command line that runs it. init and login stay in the app. Every other command runs in line mode after the app closes.

When the app closes, it prints the record of the run in the normal screen: one line per finished step, then the summary or the failure with its next steps. A cancelled run prints the same messages as line mode, and the exit codes are the same.

The app follows the size of the terminal while it runs:

A long URL or path is shortened with an ellipsis and stays in its own region. The output of a command keeps at least three rows.

Line mode

Line mode prints each step as a line and draws no screen. The CLI uses line mode in each of these cases:

• You pass --no-tui, or the NO_TUI environment variable has a nonempty value other than 0 or false (case-insensitive).
• The standard input or the standard output is not a terminal.
• The CI environment variable is set, or TERM is dumb.
• The terminal is smaller than 60 columns by 12 rows.
• The command runs with --json.

agents init --no-tui
NO_TUI=1 agents login

Commands

Exit codes

deploy, builds, rollback, and redeploy share these codes. Their --help output lists them:

terms uses codes 2 and 3 with its own meanings: a confirmation is needed and nothing was recorded (2), or you are not signed in (3).

Three results exit with code 0 although the work is not finished. Check the output for them in a script:

• deploy prints Only the push was verified when it cannot read the build. See deploy.
• deploy --no-wait returns after the push and does not follow the build.
• unpack without a package name lists the packages and unpacks nothing.

JSON output

Every command writes errors and warnings to stderr, and status lines and results to stdout.

With --json, stdout holds exactly one JSON document, and status lines move to stderr. diag tail --json is the exception: it prints one JSON frame per line.

For available-models, list-packed, and the diag subcommands, a command that exits with a nonzero code prints a document with an error member. error.code and error.message are always present. An unknown command or flag, or a missing argument, prints the same document with the code usage_error whenever --json is among the arguments.

The other commands that accept --json print their own documents. The README of the @standardagents/cli package shows each document and lists the error codes.

Run without a terminal

Scripts, CI jobs, and coding agents have no interactive terminal. In that case a command that needs an answer exits with code 1 and names the flag to pass.

Setting STANDARD_AGENTS_BROWSER=none has the same effect as --no-open for init and login.

STANDARD_AGENTS_BROWSER can also name the browser these two commands open: an application name on macOS and Windows ("Google Chrome"), or a command on Linux (firefox). When the browser cannot be opened, the command prints a warning, and waits while you open the printed sign-in URL yourself.

A headless sign-in, deployment, and result check:

# The setup code comes from the project's Overview page in the dashboard.
# Standard input keeps it out of the process list, where an argument is visible.
printf '%s' "$SETUP_CODE" | npx @standardagents/cli@latest login --bootstrap-stdin

# Exit code 0: the build is live. Exit code 1: the push or the build failed.
# Exit code 4: the terms need acceptance. Exit code 5: the wait timed out.
npx @standardagents/cli@latest deploy --timeout 600 --json

# One JSON document that describes the build of the checked-out commit.
npx @standardagents/cli@latest builds status --json

Platform API address

init, login, logout, builds, terms, and the Git credential helper use the first address that one of these names:

1. The flag of the command: --endpoint <url> or --api-url <url>
2. STANDARD_AGENTS_API_URL
3. PLATFORM_ENDPOINT
4. STANDARD_AGENTS_PLATFORM_URL
5. https://api.standardagents.ai

The Git credential helper and builds read the same three variables from the .dev.vars of your project after the environment.

--endpoint and --api-url are two names for one option, and every command that takes a platform address accepts both. The help of init lists --api-url; the help of the other commands lists --endpoint. When a command line has both, the CLI uses --api-url.

The CLI sends your session or API key to this address, so the address must use HTTPS. Plain HTTP is accepted only for this machine: localhost, 127.0.0.1, or [::1]. For any other address the command exits with code 1 before it sends a request, and the message shows the https:// address to use. An address that contains a user name or a password is refused in the same way.

A request that carries your session, API key, or setup code is never redirected. When the platform answers with a redirect, the command stops and names the host. Check the platform address.

Request time limits

Each request to the platform, to an instance, or to the model guide ends after 30 seconds without a complete answer (15 seconds for each model guide address). The message names the host that did not answer and the command to run next. Waiting for a browser sign-in or for a build has its own limit: the lifetime of the sign-in session, or --timeout.

Where credentials are stored

The CLI configuration directory is $XDG_CONFIG_HOME/standardagents when XDG_CONFIG_HOME is set. Otherwise it is ~/.config/standardagents on macOS and Linux, and %APPDATA%\standardagents on Windows.

The CLI writes .dev.vars and auth-state.json so that only your user can read them. Before each write to .dev.vars, the CLI adds .dev.vars and .agents to your .gitignore when Git does not ignore them. When Git tracks .dev.vars, the CLI writes no credential into it and prints the git rm --cached command that stops the tracking.

Your sign-in is saved once for the machine. No project file holds an account session. Releases through 0.45.5 saved a project session in .agents/bootstrap-session.json and in .dev.vars. No command reads those values any more, and logout removes them. If you signed in only with that project sign-in, run npx @standardagents/cli@latest login once.

On macOS, login keeps the account session and the account API key in the Keychain, and auth-state.json holds no secret. The secret never appears in the arguments of a process. On Linux and Windows the CLI supports no credential store, so auth-state.json holds both values, readable only by your user. The same file is used on macOS in two cases:

• The Keychain is not available, for example because it is locked in an SSH session. login says so.
• You set STANDARD_AGENTS_CREDENTIAL_STORE=file when you run login.

A sign-in that an earlier release saved in auth-state.json keeps working. It moves to the Keychain the next time you run login on macOS. A sign-in saved from a desktop session is in the Keychain, which an SSH session cannot read until you run security unlock-keychain; whoami, terms, the build commands, and the credential helper say so. To use one sign-in from both, run login with STANDARD_AGENTS_CREDENTIAL_STORE=file.

The credential helper stores no password. Each time Git contacts a Standard Agents repository, the helper requests a short-lived token from the platform. It uses the project API key from the nearest .dev.vars first. When the platform refuses that key, the helper names it on the error stream and tries your sign-in for this machine.

These environment variables also sign the CLI in, and they take effect until you unset them: STANDARD_AGENTS_API_KEY, STANDARD_AGENTS_SESSION_COOKIE.

logout removes the stored credentials and revokes the ones that the platform can revoke.

When a build fails

deploy and builds status --wait exit with code 1 when a build fails, and they print the error message from the platform.

1. Read the build log:

   agents builds logs

   Without a build ID, the command reads the newest build of the checked-out commit. To choose another build, list the builds with agents builds and pass an ID.

2. If the log shows an error in your project, correct it, commit, and deploy again:

   agents deploy

3. If the failure needs no change to your code, run the same build again and wait for its result:

   agents builds retry --wait

4. If production is broken after a build went live, make the earlier production build live again, then correct the code in a new commit:

   agents rollback --yes --wait

deploy and builds use the project API key in .dev.vars, or your account sign-in from agents login. rollback and redeploy need the account sign-in, by an owner or admin of the account that owns the project. Without a stored sign-in or key, deploy reports Only the push was verified, and the other commands exit with code 3.

Exit code 4 means that the platform stored your push and waits for the terms. Run terms accept. An acceptance starts no build by itself: the command offers to start each deploy that waits, and agents builds retry starts one later.

The local build script of a project stops with a message. Builds run on the platform from your committed package.json and lockfile, so commit both.

Project commands

init

agents init [project-name]

Creates a project on the Standard Agents platform and sets it up on your machine. The command prints a sign-in URL and opens your browser. After you sign in and create the project there, it clones the project repository into the current directory, writes .dev.vars, registers the Git credential helper for the repository, installs dependencies, and starts the dev server on 127.0.0.1. It stays attached to the dev server until you press Ctrl-C.

Before the install, init sets every Standard Agents Builder package in package.json to the latest release and prints that version. These packages ship together, so a project names each of them at the same exact version, with no ^ or ~. A lockfile that names an older release is updated by the install. @standardagents/sip has its own version and is not changed. A prerelease CLI, run as @next or @dev, uses its own version instead of the latest release. If npm does not answer within 10 seconds, init prints a warning and installs the versions already in package.json. Commit the changed package.json and lockfile.

project-name fills in the name field of the browser form.

The command also accepts hidden compatibility and contributor options: --local selects local scaffolding, --template <template> selects its Vite template (default: vanilla-ts), and -y / --yes skips its prompts. --workspace links local packages with pnpm. --bootstrap <code>, --bootstrap-stdin, and --bootstrap-file <path> accept a platform setup code.

The command exits with code 1 when the dev server does not start or stops with an error. Your project stays cloned and configured, and the output ends with the commands that start the server again.

scaffold

agents scaffold

Adds Standard Agents to the Vite project in the current directory. It adds @standardagents/builder and @standardagents/spec to package.json, adds the builder() plugin to your vite.config, sets the registry for the @standardagents scope, adds the generated type files to tsconfig.json, and creates the agents/ directories with an AGENTS.md guide in each one.

scaffold does not install dependencies, sign you in, or write .dev.vars. The root AGENTS.md that it writes lists those remaining steps. It keeps your application files. Without --force it keeps an AGENTS.md that already exists, and it says how many kept guides differ from the current version.

The command runs five stages: vite-config, package-json, registry-pin, guides, and tsconfig. It exits with code 1 when a stage fails. It names that stage and the command that resumes it, completes the other stages, and keeps the files that it wrote.

support-files

agents support-files

Writes the local support files of a project repository that you cloned yourself. init runs the same step for you. The command writes a package.json when the repository has none, adds local build and development directories to .gitignore, and sets the registry for the @standardagents scope. It keeps files that already exist.

The command exits with code 1 when it cannot set the registry, after it prints the setting to add by hand.

init-chat

agents init-chat [project-name]

Creates a React chat application in a new project-name directory. The application connects to a running Standard Agents instance. In a terminal, the command asks for the framework, the address of the instance, and the package manager. It then installs dependencies, starts the dev server of the chat application, opens the browser, and stays attached to the server.

Without a terminal, the command never asks. It needs project-name, and either --yes or a flag for each of the three values. It installs dependencies, prints the command that starts the dev server, and exits. It starts the server only when you pass --dev.

agents init-chat my-chat --yes
agents init-chat my-chat --framework nextjs --instance-url http://localhost:5173 --package-manager pnpm

The command exits with code 1, before it creates anything, when a value is missing or not supported, or when the directory already exists. It also exits with code 1 when the installation fails. When the dev server exits with an error, the command exits with the same code.

Account commands

login

agents login
agents login --bootstrap-stdin

Signs you in to your Standard Agents account. It is the one sign-in command, and it works in any directory. It never creates a project.

The command prints the sign-in URL, opens your browser, and waits until you approve the sign-in. Ctrl-C cancels the sign-in on the platform too. The command then does these things:

1. It saves one sign-in for this machine: an account session and a long-lived account API key. terms, builds, deploy, rollback, redeploy, and Git all use it, in every directory.
2. It registers the credential helper in your global Git configuration for git.standardagents.ai and git.standardagentbuilder.com only.
3. Inside a project that has no project API key, it saves that key in .dev.vars. The local instance needs the key before you can sign in to it with your account. An existing key is kept.

The command finds the project from the Git remote of your checkout, or from a setup code that names the project. The setup code comes from the project's Overview page in the dashboard. When the command cannot get a project API key, it says why, and the sign-in for the machine is still saved.

Pass the setup code one way. The command exits with code 1 when it receives two, or when the file or the standard input holds no code.

When the project still has a published default admin password and the command cannot save a project API key, the command replaces the password with a random one. It saves the new password as SUPER_ADMIN_PASSWORD in .dev.vars and does not print it.

The registered helper command names the CLI release that ran login: npx -y @standardagents/cli@<version> git-credential. Git therefore never starts a release that you did not run yourself. Run login again after you update the CLI to register the new release. init registers the helper of its own release in the cloned repository in the same way.

The command sets useHttpPath for the two Standard Agents hosts, because one host serves many repositories. Releases through 0.45.5 set credential.useHttpPath for every Git host. The command removes that global value when your global Git configuration has no other credential setting. Otherwise it leaves the value and prints the command that removes it.

The sign-in includes an account API key that does not expire, so Git and the build commands keep working after the browser session ends. When you run login again as the same user of the same account, the command keeps that key. When the saved key belongs to another user, account, or platform, the command revokes it before it creates a new one. The number of active keys for the machine therefore stays at one. A key that could not be revoked is named in a warning.

agents git-login is an earlier name of this command. It accepts the same flags and does the same work.

whoami

agents whoami
agents whoami --json

Prints the user, the account, and the platform address of the sign-in that login saved on this machine. The command reads the saved sign-in and sends no request, so it works offline. It never prints the session or the key.

The command exits with code 0 when a sign-in is saved. When the Keychain does not return the saved session and key (for example in an SSH session), the command still prints the account, reports the credential as unreadable, and names security unlock-keychain. It exits with code 3 when there is none, and names the login command. With --json that result is { "ok": false, "error": { "code": "NOT_SIGNED_IN", "message", "fix" } }.

logout

agents logout

Removes every stored credential: your sign-in for this machine and STANDARD_AGENTS_API_KEY in the nearest .dev.vars. It also removes a project session that a release through 0.45.5 saved. It then revokes the project API key, the account API key of this machine, and the account session on the platform, which also signs you out of the dashboard. The output lists what the command removed, what it revoked, and what still works.

Each API key revokes itself, so the command needs no session for it. A platform that has no route for this reports the project API key as still valid; the key is gone from this machine, and you revoke it under API keys in the dashboard. Credentials in environment variables stay until you unset them.

The command exits with code 1 when a credential on this machine still works or a revocation failed. The local credentials are removed in both cases.

git-credential

agents git-credential <operation>

The credential helper that init and login register. Git runs it; you do not need to. It follows the Git credential helper protocol: Git writes the request to the standard input, and the helper prints a user name and a short-lived password.

The helper answers the get operation for HTTPS requests to git.standardagents.ai and git.standardagentbuilder.com. It prints nothing for other hosts and other operations, so your other credential helpers keep working. When it has no credential for a Standard Agents host, it prints the login command on the error stream.

The helper requests a token that can only read for git clone, git fetch, git pull, and git ls-remote, and a token that can also write for every other command. Git does not tell a credential helper which command runs, so the helper reads it from the git process that started it. When it cannot, it requests a write token, as earlier releases did for every command. STANDARD_AGENTS_GIT_TOKEN_SCOPE=write (or read) sets the scope yourself.

The helper reads .dev.vars as the local runtime reads it, so quoted values, export lines, and comments are understood.

Deployment commands

deploy

agents deploy

Pushes the checked-out commit to the branch of the same name on the origin remote, then follows the platform build of that commit and reports the result. The command does not use push.default or the upstream setting of the branch. It exits with code 2 when the remote is not a Standard Agents repository, or when no branch is checked out and you pass no --branch.

A push to the default branch deploys to production. A push to another branch deploys a preview.

When the remote branch already has the commit, the command pushes nothing and reads the existing build of that commit.

builds

agents builds                    # recent builds, newest first
agents builds status [build]     # one build and its error message
agents builds logs [build]       # the log of one build
agents builds retry [build]      # run a failed build again without a new commit

[build] is a build ID or a unique prefix of a build ID. A commit prefix selects its newest build when all matches belong to one commit. Without it, status and logs use the newest build of the checked-out commit, or the newest build when that commit has none. retry uses the newest build of the checked-out branch, when that build failed.

These commands use the project API key in .dev.vars, or your account sign-in. They exit with the shared codes.

rollback

agents rollback [build]

Makes an earlier production build live again. Without [build], the target is the production build that was live before the current one. The command accepts only a production build that was live earlier.

The command asks for confirmation in a terminal. Without a terminal it changes nothing and exits with code 2 unless you pass --yes. It needs an account sign-in from agents login; a project API key is not enough.

redeploy

agents redeploy

Deploys the live production build again, so that changed environment values take effect. No build runs. The command needs an account sign-in from agents login.

Model commands

current-models

agents current-models

Prints the current model guide as Markdown. The command requests https://standardagentspec.org/models.md first, and https://standardagentspec.com/models.md when the first request fails. It needs no project and no sign-in.

The command exits with code 1 when no address returns the guide. An address that does not answer within 15 seconds counts as failed.

available-models

agents available-models --provider=openai

Lists the model IDs of one provider as a Markdown table. Run it from a project with its dependencies installed. The command uses the provider's own key when the project has one. Otherwise it uses the account key of the project, STANDARD_AGENTS_API_KEY.

The command exits with code 1 when a key is missing, the request fails, or the provider returns no models. It also exits with code 1, before any request, when the account key would go to a platform address that is neither HTTPS nor on this machine.

Coding agent commands

skill

agents skill

Installs the agentbuilder skill for your coding agent. In a terminal, the command asks which target to install. See @standardagents/skill for what the skill covers.

--agent codex is an alias of --agent agents. The command exits with code 1 when the skill is already installed without --force.

Packing commands

Run these commands from the root of a project with its dependencies installed. They use the Standard Agents Builder that the project installs. Without it, each command prints the install command and exits with code 1.

pack

agents pack [agent-name]

Packs an agent and everything it depends on into a package in agents/packed/. The command then removes the original files that only that agent uses, and it lists those files before it removes them. It keeps files that another agent also uses.

unpack

agents unpack [package]

Copies a packed agent into editable files under agents/. Without package, the command lists the packages that it found and exits with code 0. It has no flags.

list-packed

agents list-packed

Lists the packed agents in agents/packed/ and in the installed packages of the project, with their version, source, and entry agent.

Diagnostic commands

diag

agents diag instance
agents diag threads
agents diag thread <id>
agents diag logs <thread> [logId]
agents diag tail <thread>
agents diag revive <thread>

Diagnoses a running instance: a local dev server or a deployed project. These commands read the request logs of an instance. Build logs are in builds.

<id> and <thread> accept the start of a thread ID.

Each command prints one line that starts with diag: on stderr and exits with code 1 when the instance cannot be reached, does not answer within 30 seconds, or refuses the request. A --token is sent only to an HTTPS instance address, or to plain HTTP on this machine; any other address exits with code 1 before a request. A request with a token is not redirected. diag tail exits with code 0 when the stream closes normally, and with code 1 when the connection fails or closes abnormally.

Terms commands

terms

agents terms
agents terms accept

terms shows the Terms of Service and the Privacy Policy that are in force: each title, version, and URL, and whether you accepted that version. terms status does the same.

terms accept shows the same documents and the acknowledgement sentence, then asks for your confirmation. An acceptance starts no build. The command lists each deploy that waits and asks whether to start it; with --agree it starts them without a second question. To start one later, run agents builds retry in its project on the branch that you pushed.

Both commands use the sign-in that login saved on this machine, so they work in any directory. An API key cannot accept terms, because acceptance belongs to a person.

Without a terminal, terms accept records nothing and exits with code 2. It prints the two links, the acknowledgement sentence, and the command that accepts those versions. A coding agent shows you the links and the sentence, and runs that command only after you say yes. When a document changed after you reviewed it, the command records nothing, exits with code 2, and prints the current documents.

Generate types

The dev server generates the type files of a project. It writes .agents/types.d.ts and .agents/virtual-module.d.ts when it starts, and again after each change under agents/:

npm run dev

Start the dev server once before you run the type checker in a new project. The type checker reports missing type files until then. There is no separate type-generation command.