Amp commands and subcommands

Starts the Amp CLI. Without arguments it runs in interactive mode; piped input becomes the first user message in interactive mode.

Adds an account and makes it active for the current Amp server. Required before cloning private projects or plugins and skills repositories.

Removes the active saved account, or a specific account when given an email or user ID. Does not sign out browser or native app sessions.

[<email-or-user-id>]

Shows saved CLI accounts.

Chooses the account used by future CLI commands. Already running CLI processes keep the account they started with.

<email-or-user-id>

Prints shell completion setup for commands, aliases, options, and argument choices. Completions work without signing in or a network connection.

bash | zsh | fish | pwsh

Manually checks for and installs updates. Amp also checks and installs new versions automatically in the background.

Shows which version of Amp is installed.

Opens your user settings file in $EDITOR. Add --workspace to edit workspace settings.

Shows the full map of keyboard shortcuts and all available commands.

Adds a term that Amp mishears to your custom dictation vocabulary.

<term>

Manages model routing connections (API keys, subscriptions, cloud platforms, routers) from the CLI, with the same operations as Model Routing settings.

Lists model routing connections and their current priority. list --json also shows priorities.

Sets a connection's priority; 0 is tried first and other connections at or after that priority move down one place.

<connection-id> <priority>

Verifies a connection's credential with the provider, like the Check Access button.

<connection-id>

Runs one short inference for a model and reports which connection actually served it.

--provider-model <provider/model>

Activates an inactive connection so it is used during routing again.

<connection-id>

Deactivates a connection so it is skipped during routing while keeping its settings. Asks for --yes before deactivating a subscription.

<connection-id>

Edits a router or gateway connection, for example its model mapping.

<connection-id> [--model-mapping <patterns>] [--clear-model-mapping]

Edits an API key connection, for example its model mapping.

<connection-id> [--model-mapping <patterns>] [--clear-model-mapping]

Shows a connection, including nonblocking warnings about its model mapping.

Opens the Sign in with ChatGPT flow in your browser so OpenAI model usage can bill to your ChatGPT subscription.

Short form of amp config model-providers add-chatgpt-subscription.

Attaches the CLI to an existing thread. Combined with -ox it sends one message to the thread's own orb without attaching; combined with --execute it continues the thread in execute mode.

[T-...]

Changes the sharing visibility of a thread.

<thread> --visibility <private|workspace|group|unlisted>

Exports a thread as Markdown.

<thread>

Exports a thread's full JSON (available to the thread's creator).

<thread>

Labels a thread from the CLI.

Renames a thread from the CLI.

Archives a thread from the CLI.

Permanently deletes a thread from the CLI.

Lists threads without opening the web app.

Searches threads without opening the web app.

Mirrors an orb thread's changes into your local checkout while the agent keeps working remotely.

<thread> (URL or ID)

Clones a repository hosted by Amp: an Amp-hosted project or a personal or workspace plugins or skills repository. Sets up Amp as a Git credential helper in your global Git config.

owner/project-name | project URL | user-plugins | user-skills | workspace-plugins | workspace-skills | owner/-/plugins | owner/-/skills [directory]

Installs a skill directly from a GitHub repository, Git URL, or local path. Pass --global to install it only on the current machine under ~/.config/agents/skills/.

<source> [--global]

Manages shared skill imports into a skills repository.

Updates one imported skill from a checkout of its repository. Review, commit, and push the update to publish it.

<name>

Lists available skills; add --json for machine-readable output. Running it in another shell does not reload an existing session.

[--json]

Lists the skills repositories available to you, their clone commands, and whether you can write to them.

Installs a single-file plugin from a URL as a machine-local system plugin for all projects. Add --target workspace to install into the current project's .amp/plugins/ directory.

<url> [--target workspace] [--auto-update]

Shows loaded plugins, their sources, registered events, commands, and tools.

Lists the plugin repositories available to you, their clone commands, and whether you can write to them.

Manages shared plugin imports into a plugins repository.

Updates one imported plugin from a checkout of its repository.

<name>

Lists the model IDs and built-in tools available to custom plugin agents.

Prints the Plugin API documentation installed in the current environment, for example inside an orb.

Lists local tools, useful for finding tool names to call from plugins.

Shows a local tool, including its input schema with --json.

<name> [--json]

Adds a local MCP server to your configuration, either a command after -- or a remote URL.

<name> -- <command...> | <name> <url>

Approves a workspace MCP server from .amp/settings.json so it can run.

<server-name>

Shows MCP server status, including awaiting approval for workspace servers that need approval.

Registers manual OAuth client credentials for a local MCP server; Amp opens the browser to finish authentication when the TUI starts.

<server> --server-url <url> --client-id <id> --client-secret <secret> --scopes <scopes>

Clears stored OAuth credentials for a local MCP server so Amp reauthenticates on next startup.

<server>

Manages remote MCP definitions stored by ampcode.com in personal, workspace, or project scope. Every command needs one scope option, before or after the command.

add | list | update | check | tools | login | logout | remove

Adds a remote MCP definition. Amp detects authentication when --auth is omitted.

<name> <url> [--auth none|bearer|oauth|workload-identity]

Lists remote MCP definitions in the selected scope; --json returns the UUID id used by other commands.

Updates a remote MCP definition by name or UUID, for example disabling it.

<name-or-uuid> [--disabled]

Checks a remote MCP definition.

<name-or-uuid>

Lists a remote MCP server's tools; --refresh refreshes them.

<name-or-uuid> [--refresh] [--json]

Logs in to a remote MCP definition; prints the ampcode.com OAuth URL, useful in orbs where browser OAuth is unavailable.

<name-or-uuid>

Logs out of a remote MCP definition.

<name-or-uuid>

Removes a remote MCP definition.

<name-or-uuid> [--yes]

Checks what a runner can share for the Desktop tab and, on Linux, lists which required programs it finds.

Asks macOS again for a permission the runner desktop needs.

screen-recording | accessibility

Adds a directory to a running runner from another terminal on the same machine. Added directories are served again when the runner restarts from the same directory.

<path> [--runner-id <id>]

Lists the directories a running runner serves.

[--runner-id <id>]

Removes a directory from a running runner.

<path> [--runner-id <id>]

Sends a bug report with diagnostic data to the Amp team, for example after an amp --no-tui runner has stopped (run in the runner directory). amp report and amp diagnostics are aliases. Diagnostic data is deleted after 7 days.

"<description>"

Alias for amp report-bug.

Alias for amp report-bug.

Manages Secrets & Env Vars from the CLI. Run amp secrets --help to see the available operations.

Shows who created and last changed each secret or environment variable entry, without showing values.

Run from an orb's Terminal to refresh secrets: waits for the current command, reloads values, and restarts the executor and managed services.

Inside an orb, mints a signed OpenID Connect ID token for one intended service and prints only the token to standard output.

--audience <aud> [--ttl-seconds <n>] [--subject-scope thread|user|project|workspace]

Reads .amp/services.yaml, starts any missing declared services, waits for readiness, writes Portal tab state, and prints the portal URLs. Add --json for structured status.

[--json]

Lists supervised services in the orb.

Shows the status of a supervised service.

<name>

Shows the logs of a supervised service.

<name>

Restarts a service, reading the latest .amp/services.yaml and keeping its port and portal configuration.

<name>

Stops a supervised service.

<name>

Starts a one-off supervised service for the current thread. Rejects names already declared in .amp/services.yaml; waits up to 60 seconds for the port with --portal.

<name> --command <cmd> [--portal] [--title] [--description] [--cwd] [--port]

Lower-level command that creates or prints a portal URL for a server already listening on a port and registers it in the Portal tab. Does not start or supervise the server.

<port> [--title] [--description] [--hostname <hostname>] [--take-over]

Creates a project mapped to an existing GitHub or Git repository, a blank Amp-hosted project with --amp-hosted, or an Amp-hosted project from a local repository with --push.

[<repo>] [--amp-hosted --name <name>] [--push [--remote <name>]] [--personal | --workspace]

Updates project settings from the CLI. With no update options it refreshes a GitHub-connected project's repository metadata.

<namespace/name> [options]

Deletes a project; its threads are always kept, archived, and read-only.

<project>

Lists a project's cached orb snapshots.

<project>

Deletes cached orb snapshots so a setup change applies right away. Omit --resource to delete every snapshot for the project.

<project> [--resource <size>]