Amp CLI reference

Typing / in an empty prompt opens the CLI command palette, like Ctrl+O.

Command palette command that connects Amp to VS Code, Cursor, Windsurf, Zed, or Neovim so it sees the open file and selection and edits through the IDE.

Command palette command that pastes a clipboard image when the terminal intercepts Ctrl+V.

Command palette command (type queue) that queues the message until the agent finishes its whole turn instead of steering it.

Command palette command that opens $EDITOR to write a prompt.

Typing mode in the command palette turns the Dial before the thread's first message.

Command palette command that changes the current thread's sharing visibility.

Command palette command that toggles amp.remoteThreadCreation.enabled so ampcode.com can create threads in this TUI.

Command palette command that lists each workspace-managed key, its value, and whether it replaces or merges with a local value.

Command palette command that lists available skills.

Command palette command that reloads plugins after a change.

Command palette command that lists plugins available in the thread.

Command palette command that opens a bug report form; describe the bug and submit.

Command palette command that archives the current thread.

Command palette command that starts a new orb thread from the TUI.

Command palette command that chooses the project before starting an orb thread.

Command palette command that creates an Amp project when the repository does not have one yet.

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

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>]

Opens the command palette, Amp's most important CLI shortcut. In a plugin dialog with link fields it opens the first link.

Opens the current prompt in your editor. Requires $EDITOR.

Pastes an image from the clipboard into the prompt, even on macOS (not Cmd+V).

Turns the Dial before a thread's first message; afterwards it shows the thread's mode and models, which cannot change. Keymap command mode.toggle.

After Ctrl+S, switches to a list of every mode (dial modes first); use Up and Down to choose and Tab again to return to the dial.

Opens your prompt history. For an amp --no-tui runner, Ctrl+R reports a bug.

Moves to queued and previous messages so you can edit them.

Edits a prior message: Tab navigates to prior messages and e edits the selected one.

Expands or collapses thinking and tool call details for the current session.

Toggles fast mode for the active model.

Archives the current thread and starts a new one.

Archives the current thread and quits.

Quits the CLI.

Copies an active transcript selection manually when amp.terminal.copyOnSelect is false.

Interrupts the active agent turn (forcibly stops the agent and sends your message immediately). Keymap command thread.interrupt.

In the TUI, searches for a file to mention. In the web composer, @ tags a workspace member.

In the CLI, searches for a thread to mention.

Submits the prompt. If the agent is still working, Enter steers it by default: the message is delivered after the current step.

On a queued message, steers it sooner.

Inserts a newline when the terminal supports modified Enter keys (Ghostty, WezTerm, Kitty, iTerm2, or tmux with extended-keys enabled).

Inserts a newline in any terminal.

Typing a backslash followed by Return inserts a newline.

The leader key used in keymap chords; <leader> u means Ctrl+X then u. Change it by defining a keymap entry for "leader".

default Ctrl+X

In the web composer, queues the message until the agent completely finishes instead of steering.

Snoozes the current thread in the web app.

Starts and stops voice dictation (Cmd+Shift+D on macOS, Ctrl+Shift+D elsewhere); press and hold to dictate and send on release. Configurable in Keyboard Shortcuts settings.

Opens App Settings in the Amp app for macOS, where the Runner tab lives.

The JSON Schema URL used by your editor for validation, descriptions, and completions in settings files.

string, e.g. https://ampcode.com/cli-settings.schema.json

Glob patterns for paths always included in fuzzy file search even if ignored by Git, useful for build output or generated files referenced with @ mentions.

array of strings, default []

Shows cost information for threads in the CLI while working. Workspace admins can also hide costs for all members.

boolean, default true

Adds the Amp-Thread-ID: <thread-url> trailer to agent Git commits. While disabled, Amp refuses to run a git commit whose message writes the trailer by hand.

boolean, default true

Adds the Co-authored-by: Amp <amp@ampcode.com> trailer to agent Git commits. Never added in remote orbs whose project Git identity is Amp.

boolean, default true

Customizes CLI keybindings. Configuring a command replaces its default; use an array to keep the old shortcut, or null to unbind. User keymap entries override workspace entries.

object mapping command IDs to string | string[] | null, default {}

Keymap command ID shown in the amp.keymap example; bound to Ctrl+S by default per the keybindings page.

string | string[] | null

Keymap command ID shown in the amp.keymap example for copying the thread URL.

string | string[] | null

Keymap command ID shown in the amp.keymap example for interrupting the agent (default Esc Esc).

string | string[] | null

Keymap entry that changes the <leader> key (default Ctrl+X).

string

Local (stdio) MCP server field: the command to run. Required for stdio servers in amp.mcpServers and skill mcp.json.

string

Local MCP server field: the command arguments.

string[] (optional)

Local MCP server field: environment variables for the server.

object of strings (optional)

Remote MCP server field: the server endpoint. Required for HTTP servers.

string

Remote MCP server field: HTTP headers sent with requests. Can contain ${amp:id-token} for HTTPS servers in orbs.

object of strings (optional)

HTTP MCP server field in the settings JSON Schema selecting the transport.

http | sse | http-first

HTTP MCP server field in the settings JSON Schema for OAuth client configuration.

object: clientId (required), clientSecret, authUrl (required), tokenUrl (required), scopes (string[]), redirectUrl

Common field for MCP servers defined in skills: tool names or glob patterns that choose which tools are exposed. Optional but recommended.

string[]

Header placeholder that makes Amp send an Amp ID token to an HTTPS MCP server in an orb. Works only in headers of HTTPS servers without OAuth; outside an orb the server fails to connect.

Defines default thread visibility per repository origin.

object mapping origin to private | workspace | group

Plays notification sounds when the agent completes a task or is blocked waiting for input. Over SSH, or when AMP_FORCE_BEL is set, Amp sends a terminal bell instead.

boolean, default true

Lets ampcode.com create new threads that open in the interactive TUI on this machine, in the directory where it was started.

boolean, default false

Lets amp --no-tui runners install CLI updates and restart into them once no thread is running, at most once every 12 hours, keeping their flags.

boolean, default true

Lets amp --no-tui runners inject ampcode.com Secrets & Env Vars into threads' shell commands, MCP servers, and plugins. Same as --amp-env.

boolean, default false

Disables loading skills from Claude Code directories (.claude/skills/, ~/.claude/skills/, ~/.claude/plugins/cache/).

boolean, default false

Disables loading skills from ~/.config/agents/skills/ and ~/.agents/skills/.

boolean, default false

Additional directories containing skills, colon-separated (semicolon on Windows). ~ expands to home; relative paths resolve against the workspace root.

string

Copies transcript selections to the clipboard automatically. When false, press Ctrl+C to copy a selection.

boolean, default true

Expands thinking and tool call details by default in the CLI transcript.

boolean, default false

Automatically archives the active thread and connected background threads when quitting Amp.

boolean, default false

Disables specific tools by name. Use builtin:toolname to disable only the built-in tool; * globs are supported.

array of strings, default []

Allows or blocks MCP servers that match a pattern; the first matching rule applies and unmatched servers are allowed. Match remote servers by url and local servers by command and args.

array of {matches: object, action: allow | reject}, default []

Controls update checking: warn shows notifications, disabled turns checks off (also disables runner auto-update), auto installs updates. AMP_SKIP_UPDATE_CHECK=1 overrides it.

"auto" | "warn" | "disabled", default "auto"

Managed-settings field giving the date used to determine which backward-compatibility migrations Amp must apply. Supported in managed-settings.json and the workspace document.

string, YYYY-MM-DD

Setting named as not allowed in the workspace managed settings document because it could make the client unable to reach the server that provides the settings.

Setting named as not allowed in the workspace managed settings document because it could make the client unable to reach the settings server.

Setting that is local to one machine and therefore cannot be set in the workspace managed settings document.

Setting that is local to one machine and therefore cannot be set in the workspace managed settings document.

Skill name in SKILL.md YAML frontmatter. Amp uses the first skill with a given name; in hosted repositories it must match the directory name.

string

Skill description the model sees and uses to decide when to load the skill.

string

Defines MCP servers for a skill. If both mcpServers and a sibling mcp.json exist, Amp uses mcpServers.

object of MCP server definitions

In a plugin-bundled skill, lists the plugin's own tools so they stay hidden from the model until the skill is loaded.

list of tool names

YAML front matter in an @-mentioned guidance file so it is included only after Amp reads a matching file. Globs are implicitly prefixed with **/ unless they start with ../ or ./.

string[]

.amp/services.yaml field: required shell command run through a login shell. A service with a portal must listen on $PORT.

string

.amp/services.yaml field: working directory relative to the repository root.

string, default repository root

.amp/services.yaml field: fixed local port. Omit to let Amp choose a free port that stays the same across restarts.

integer 1 to 65535

.amp/services.yaml field: string environment variables for the command; values can refer to another service's public URL. PORT, PUBLIC_URL, and AMP_THREAD_ID cannot be set.

object of strings

.amp/services.yaml field: HTTP path Amp requests after the port opens; 2xx and 3xx mean ready.

path string

.amp/services.yaml field: primary portal link. true means / with the service name; or a mapping with url, title, description.

true | {url, title, description}

.amp/services.yaml field: more portal links for the same service; each needs url and title, and folders can group links.

list

.amp/services.yaml field: whether Amp injects the portal review widget.

boolean, default true

.amp/services.yaml field: optional nonempty list of platforms the service runs on; omit to run on all platforms.

[linux] | [darwin] | [linux, darwin]

Access token for non-interactive environments such as scripts and CI. Must be a Settings access token starting with sgamp_; takes precedence over saved accounts. Reserved and cannot be stored as an orb secret.

sgamp_... access token

Set to 1 to stop adding the Amp-Thread-ID trailer to agent commits, like amp.git.commit.ampThread.enabled=false.

1

Set to 1 to stop adding the Co-authored-by: Amp trailer. Can be set as a personal, project, or workspace environment variable for orbs.

1

When set, Amp sends a terminal bell for notifications instead of using host audio.

Set to 1 to override amp.updates.mode and disable all update checks.

1

When neither terminal flag is passed, 1 enables web terminal access and 0 disables it. An explicit CLI flag takes precedence.

1 | 0

Set to 1 to make amp clone skip setting up Amp as a Git credential helper.

1

Colon-delimited list of globs matched against absolute paths of guidance files to skip. '*' ignores all guidance files.

colon-delimited globs

Standard Node.js variable for using the CLI behind a corporate proxy.

proxy URL

Standard Node.js variable for using the CLI behind a corporate proxy.

proxy URL

Standard Node.js variable pointing to custom certificates for corporate networks.

path to PEM file

Editor used by Ctrl+G and the editor command to write prompts, and by amp config edit.

editor command

If set, system plugins are loaded from $XDG_CONFIG_HOME/amp/plugins/ instead of ~/.config/amp/plugins/.

path

Available inside an orb; the immutable workspace UUID, used for example when configuring Tailscale trust credentials.

UUID

Available inside an orb; the project UUID.

UUID

Set inside an orb; the docs use it to allow all Vite hosts only inside an orb.

Managed by Amp and given to every declared orb service; a service with a portal must listen on it.

port number

Managed by Amp and given to services with at least one portal link; read it at runtime when the application needs its public origin.

URL

Managed by Amp and given to every declared orb service.

thread ID

The only placeholder supported in a portal entry; Amp replaces it in url, title, and description (URL-encoded in url).

Set by Amp to the exact Portal hostname when it starts a portaled service, so Vite 6.1 and later allow it.

hostname

Inherited by threads served by a Linux runner started with --desktop so graphical programs open in its virtual desktop.

Entries added under project Secrets & Env Vars to give orbs clone credentials for private repositories outside GitHub. Mark GIT_CONFIG_KEY_0 as a secret.

User settings file on macOS and Linux (or settings.jsonc). On Windows: %USERPROFILE%\.config\amp\settings.json or settings.jsonc.

Workspace settings (or .amp/settings.jsonc), found by searching upward from the current directory to the repository root. Overrides user settings, except for keymaps; MCP servers here need approval.

Admin-deployed managed settings file. Paths: macOS /Library/Application Support/ampcode/managed-settings.json, Linux /etc/ampcode/managed-settings.json, Windows %ProgramData%\ampcode\managed-settings.json. Takes precedence over the workspace managed document.

JSON Schema for Amp CLI user and workspace settings files.

Personal guidance file, always included if it exists; $HOME/.config/AGENTS.md is also supported.

System-wide or organization-managed guidance, always included. Also /Library/Application Support/ampcode/AGENTS.md (macOS) and %ProgramData%\ampcode\AGENTS.md (Windows).

Project plugins directory at the project root; .ts or .js files or <plugin-name>/index.ts directories. Highest precedence among plugin sources.

System plugins directory on macOS and Linux ($XDG_CONFIG_HOME/amp/plugins/ if set; %USERPROFILE%\.config\amp\plugins\ on Windows). Applies to your projects on that machine.

First skill source in precedence; machine-local skills, and the install target of amp skill add --global.

Second skill source in precedence (global agent-agnostic directory).

Third skill source in precedence (Amp user skills directory).

Project skills in the project and searched parent directories; can be committed with the project.

Claude-compatible skill locations: .claude/skills/, ~/.claude/skills/, and ~/.claude/plugins/cache/. Skipped when amp.skills.disableClaudeCodeSkills is set.

Skill definition file with YAML frontmatter inside a skill directory. Local directories are searched up to five levels below each skills root.

Sibling file in a skill directory defining MCP servers whose tools stay hidden until the skill loads.

Executable script at the repository root that prepares new project orbs and their snapshots. Stopped after 20 minutes; log at /home/user/.cache/amp/logs/setup.log.

Executable script run after orb activation and each wake for quick authentication or repair. Amp waits up to 10 seconds; log at /home/user/.cache/amp/logs/resume.log.

Declares long-running orb services and their portal links; needs a nonempty top-level services mapping.

Generated portal link manifests for the current orb and thread; ignore in Git. Custom manifests can be written by hand.

Orb hook logs: setup.log for .agents/setup and resume.log for .agents/resume, replaced each run.

Workload identity request credential available during pre-clone, pre-setup, and .agents/setup scripts; removed after setup.

Install location of Amp Desktop Helper.app on macOS runners using --desktop.

Per-runner compositor, logs, and sockets for Linux runner desktops. Waymote is downloaded to ~/.amp/bin/waymote/<waymote-version> on x64 Linux.