Amp command-line flags

Shows more of what the CLI can do. amp clone --help shows every repository form and amp secrets --help lists the secrets operations.

Starts the CLI in execute mode: sends the given message to the agent, waits until the agent ends its turn, prints its final message, and exits. Execute mode is also turned on automatically when stdout is redirected.

prompt string (optional when input is piped)

Runs an execute-mode prompt in an orb on Amp's servers instead of on your machine. -ox is shorthand for --orb-execute -x; the CLI prints the new thread URL and exits while the agent keeps working.

prompt string

Chooses where a new thread runs: locally, in an orb, or on one of your runners. Opens the interactive TUI with that executor selected, and also works with -x.

local | orb | runner:<id> (default: local)

Chooses a directory served by the target runner for a runner thread instead of the runner's starting directory.

<absolute-path>

Enables Fast mode for one invocation. It is an alias for --features fast and works with -x and piped input; execute mode otherwise defaults to Standard mode each time.

Sets thread features for a new thread, such as fast mode, or the model and effort for Claude Code mode threads started with -x or -ox.

comma-separated features, e.g. fast, model:<id>, effort:<level>

Picks the agent mode for a new execute-mode thread. Ignored when continuing an existing thread, which keeps its mode.

mode key, e.g. low, medium, high, ultra, external-agent:claude-code

Sets the thread title for a new execute-mode thread.

string

Chooses the project an orb starts from, for example outside a checkout or when the directory matches more than one project. Without it the CLI matches the current directory's Git remotes.

Amp project (namespace/name), GitHub owner/repo, or repository URL

Runs the orb on a different size than the project default. Ignored when continuing an existing thread.

a1.tiny | a1.small | a1.medium | a1.large | a1.xxlarge | a1.3xlarge (project default a1.medium)

Uploads a local file and adds its attachment URL to the message. Repeat the flag to attach multiple files; works with -ox and runner execute threads.

<path> (repeatable)

Specifies MCP servers as JSON without changing your settings file. Servers passed this way take highest precedence and do not require workspace approval.

JSON object of MCP server definitions

Makes execute mode wait for plugins to become ready before running the turn so agent.start and agent.end events are not skipped. The turn starts as soon as plugins are ready.

optional seconds; bare flag waits up to 10; maximum 300; 0 disables the wait

Prints a timing report for execute mode to stderr when the command exits, covering startup, authentication, thread connection, execution, and cleanup. The response stays on stdout.

Outputs each message as a JSON object on its own line instead of plain text. Requires --execute; with -ox it stays attached and streams the orb thread's events until the turn ends.

Includes assistant thinking and redacted_thinking blocks in streaming JSON output. This extends the schema and is not compatible with Claude Code.

Reads user messages as JSON lines from stdin until it closes, allowing several messages in one conversation. Requires --stream-json and is not supported with -ox.

Keeps a new thread unarchived after an execute-mode turn finishes; execute mode and -ox --stream-json otherwise archive the new thread.

Points Amp at a different user settings file.

<path>

Starts a runner-only Amp instance that waits for and runs remotely created threads in the current directory without opening the TUI.

Gives a runner a stable ID. Also selects the runner for amp runner dirs commands when more than one runner is running on the machine.

<id>; must be a valid hostname, case-insensitive

Allows access to the CLI's or runner's terminal from ampcode.com. Takes precedence over AMP_REMOTE_CONTROL_TERMINAL.

Explicitly disables terminal access from the web. Takes precedence over AMP_REMOTE_CONTROL_TERMINAL.

Gives threads served by a runner a Desktop tab. On macOS threads see and control the Mac's display; on Linux the runner starts its own virtual desktop.

Makes a runner serve one more directory. Repeat for each directory; any existing directory works.

<path> (repeatable)

Makes a runner serve every Git checkout up to two levels beneath the current directory, or beneath a given path. Repeat with paths to scan several directories.

optional =<path> (repeatable); stops at 200 checkouts

Scans deeper than two levels when discovering checkouts. On its own it implies --discover-dirs for the current directory.

<levels> 1 to 10 (default 2)

Skips directories that match a .gitignore-style pattern during discovery. Repeatable; on its own it implies --discover-dirs for the current directory.

<pattern> (repeatable)

Disables automatic serving of the directory where the runner was started. Directories from --dir, --discover-dirs, and amp runner dirs add are still served.

Lets a runner inject the Secrets & Env Vars configured on ampcode.com into the shell commands, MCP servers, and plugins of the threads it serves. Off by default; same as amp.runner.env.enabled.

Shares a runner with the members of your workspace for as long as it runs. Fails if a workspace admin has disabled sharing runners.

With amp logout, removes all saved CLI accounts on every Amp server.

With amp config edit, edits workspace settings (.amp/settings.json) instead of user settings.

Sets which models a connection serves using comma- or newline-separated patterns in provider/model form; a leading - excludes and the last matching line wins.

pattern list, e.g. "*/*,-openai/gpt-5.4"

Returns a connection's model mapping to the connection type's default.

Names the model for amp config model-providers check-access.

<provider/model>

Adds additional HTTP headers to a Custom URL model routing connection when a provider needs them.

With amp threads share, sets who can open the thread.

private | workspace | group | unlisted

With amp clone, skips setting up Amp as a Git credential helper in your global Git config.

With amp skill add, installs the skill only on the current machine under ~/.config/agents/skills/; warns if amp.skills.disableGlobalAgentsSkills is set.

With amp plugins add, workspace installs into the current project's .amp/plugins/ directory, not the hosted Workspace Plugins repository.

workspace

With amp mcp oauth login, the MCP server URL.

<url>

With amp mcp oauth login, the OAuth client ID created in the server's admin interface.

<id>

With amp mcp oauth login, the OAuth client secret.

<secret>

With amp mcp oauth login, the OAuth scopes to request.

comma-separated scopes

Scope option for amp mcp remote: stores or selects the definition in your personal settings. Also used by amp projects create to make a personal project.

Scope option for amp mcp remote: stores or selects the definition in a workspace.

<workspace>

Scope option for amp mcp remote: stores or selects the definition in a project.

<project>

Scope option for amp mcp remote: selects the Amp project that matches the current repository.

Selects the authentication type for amp mcp remote add. workload-identity requires access granted by Amp staff.

none | bearer | oauth | workload-identity

Passes a bearer token for a remote MCP definition from a file; use - to read from standard input. Secret values are not accepted as command arguments.

<path> | -

OAuth client ID for a remote MCP definition with --auth oauth.

<id>

Passes an OAuth client secret for a remote MCP definition from a file; use - to read from standard input.

<path> | -

Structured output for amp mcp remote commands; also accepted by amp skills list, amp tools show, amp orb services ensure, and amp config model-providers list.

With amp mcp remote update, disables the remote MCP definition.

With amp mcp remote tools, refreshes the server's tool list.

Confirms a destructive action, such as amp mcp remote remove or deactivating a subscription with amp config model-providers deactivate.

With amp orb id-token, the intended service (aud claim) the token is minted for.

URL or URN

With amp orb id-token, the token lifetime.

60 to 3600 seconds (default 10 minutes)

With amp orb id-token, controls the shape of the sub claim; broader scopes remove narrower layers. During setup only project or workspace scopes are allowed.

thread | user | project | workspace (default thread)

With amp orb service start, the shell command to run as the service.

<cmd>

With amp orb service start, waits for the listener, detects HTTP or HTTPS, writes .amp/portals/<name>.json, and prints the URL.

Title of the portal link created by amp orb service start --portal or amp orb portal.

string

Setup or usage notes for a portal link created by amp orb service start --portal or amp orb portal.

string

With amp orb service start, the working directory for the service.

<path>

With amp orb service start, a fixed port for the service.

<port>

With amp orb portal, gives one portal a specific managed hostname (<name>--<namespace>.onamp.dev) or a hostname on a custom domain.

<hostname>

With amp orb portal --hostname, moves a custom hostname from another thread's portal to the current portal.

With amp projects create, starts the project with a blank repository hosted by Amp.

Project name for amp projects create --amp-hosted, or a new name with amp projects update.

<name>

With amp projects create, run inside a local repository to create an Amp-hosted project, add its clone URL as origin, and push the current branch. Name defaults to the directory name.

With amp projects create --push, uses a remote name other than origin.

<name>

With amp projects create, makes the workspace the project owner; --personal makes it personal.

With amp projects update, sets the project's Pre-setup Script from a file.

<path>

With amp projects update, replaces the project's additional repositories; repeat for each HTTPS URL.

<https-url> (repeatable, up to 20)

With amp projects update, removes all additional repositories.

With amp projects update, changes the primary URL of a mapped repository or migrates an Amp-hosted project to an external repository. Does not copy Git data.

<url>

With amp projects update, links the URL as a GitHub repository or treats a GitHub-linked project as a plain Git URL.

github | mapped

With amp projects update, sets the branch orbs check out and Ship targets.

<branch>

With amp projects update, clears the base branch so the repository's default branch is used.

With amp projects update, sets Git Remote Aliases used to match local CLI checkouts to the project. Each update replaces the whole list.

<url> (repeatable)

With amp projects update, removes all Git Remote Aliases.

With amp projects snapshots delete, deletes only the snapshot for one orb size.

orb size, e.g. a1.small