---
lastModified: 2026-09-19
---

# Execute Mode

Use `-x` or `--execute` to start the CLI in execute mode. In this mode, it sends the message
provided to `-x` to the agent, waits until the agent ends its turn, prints its final message, and
exits. Use `-ox` instead to run the same prompt in an [orb](/docs/orbs) on Amp's servers
rather than on your machine; see [Spawning Orbs](/docs/cli/spawning-orbs).

Run a prompt locally:

```shell-session
$ amp -x "what files in this folder are markdown files? Print only the filenames."
README.md
AGENTS.md
```

You can also pipe input when using `-x`:

```shell-session
$ echo "what package manager is used here?" | amp -x
cargo
```

Interactive CLI threads remember whether the last thread used Fast mode. Execute mode and other
noninteractive thread creation default to Standard mode each time. Pass `--fast` to enable Fast
mode for one invocation. It is an alias for `--features fast` and works with `-x` and piped input.

Execute mode is automatically turned on when you redirect stdout:

```shell-session
$ echo "what is 2+2?" | amp > response.txt
```

When you pipe input and provide a prompt with `-x`, the agent can see both:

````shell-session
$ cat ~/.vimrc | amp -x "which colorscheme is used?"
The colorscheme used is **gruvbox** with dark background and hard contrast.

```vim
set background=dark
let g:gruvbox_contrast_dark = "hard"
colorscheme gruvbox
```
````

You can use the `--mcp-config` flag with `-x` commands to specify an MCP server without changing
your settings file:

```shell-session
$ amp --mcp-config '{"everything": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-everything"]}}' -x "What tools are available to you?"
```

If your [plugins](/docs/customize/plugins) rely on the `agent.start` and `agent.end` lifecycle
events, use the `--plugin-ready-timeout` flag to make execute mode wait for plugins to become ready
before running the turn. Without it, the turn can start before plugins finish loading, and those
events are skipped. The bare flag waits up to 10 seconds. Pass a number of seconds for a different
limit. The maximum is 300, and `0` disables the wait. The turn starts as soon as plugins are ready.

```shell-session
$ amp -x "summarize this repo" --plugin-ready-timeout
$ amp -x "summarize this repo" --plugin-ready-timeout 30
```

## Spawning Orbs

Use `-ox` instead of `-x` to run the prompt in an orb on Amp's servers. The CLI prints the new
thread's URL and exits while the agent keeps working:

```shell-session
$ amp -ox "Investigate why the latest CI run on main failed"
https://ampcode.com/threads/T-…
```

See [Spawning Orbs](/docs/cli/spawning-orbs) for choosing the project and orb size, continuing an
existing orb thread, and streaming output from an orb.

## Spawning Runner Threads

Use `--executor runner:<id>` with `-x` to start a thread on one of your running
[runners](/docs/cli/runners). The CLI prints the thread URL and exits while the agent keeps
working on the runner:

```shell-session
$ amp -x "Run the tests and fix any failures" --executor runner:mac-mini
https://ampcode.com/threads/T-…
```

The thread uses the runner's starting directory by default. Pass `--runner-dir <absolute-path>`
to choose another directory served by that runner:

```shell-session
$ amp -x "Update the README" --executor runner:mac-mini --runner-dir /Users/me/code/my-app
```

Pass `--attach <path>` to upload a file from the machine where you run the command and add its
attachment URL to the message. Repeat the flag to attach multiple files:

```shell-session
$ amp -x "Implement this design" --executor runner:mac-mini --attach ./design.png --attach ./requirements.txt
```

## Non-Interactive Environments

For non-interactive environments, such as scripts and CI/CD pipelines, set your
[access token](/settings/security#access-token) in an environment variable:

```bash
export AMP_API_KEY=your-access-token-here
```

Use an access token from Settings, which starts with `sgamp_`. The CLI rejects the short-lived
session token that `amp login` stores, because it expires within an hour and cannot be refreshed
from an environment variable.