Skip to content

docs: update CLI documentation with new features and commands #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jdorfman merged 3 commits into from
Oct 16, 2025
Merged

docs: update CLI documentation with new features and commands #63

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4a8dc3a
docs: update CLI documentation with new features and commands
jdorfman Oct 16, 2025
5abce1d
Fix linting errors in amp_cli_docs.md: align tables and escape brackets
jdorfman Oct 16, 2025
479c3df
Whitelist additional npm package URLs in CI workflow
jdorfman Oct 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/lint.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,4 +42,4 @@ jobs:
- name: "install awesome-bot"
run: gem install awesome_bot
- name: "linting: ${{ matrix.files }}"
run: awesome_bot --allow-redirect --white-list https://github.com/jdorfman/awesome-amp-cli,https://example.com,https://github.com/user-attachments/assets/44099391-3976-473d-bcf8-95fd7b980f99 ${{ matrix.files }}
run: awesome_bot --allow-redirect --white-list https://github.com/jdorfman/awesome-amp-cli,https://example.com,https://github.com/user-attachments/assets/44099391-3976-473d-bcf8-95fd7b980f99,https://www.npmjs.com/package/llm-rules,https://www.npmjs.com/package/@sourcegraph/amp ${{ matrix.files }}
129 changes: 77 additions & 52 deletions docs/amp_cli_docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,56 +124,67 @@ export AMP_API_KEY=your_amp_api_key_here

Amp CLI supports the following options:

| Option | Description |
| --------------------------- | ----------- |
| `--visibility <visibility>` | Set thread visibility (private, public, team) |
| `-V, --version` | output the version number |
| `--notifications` | Enable sound notifications (enabled by default when not in execute mode) |
| `--no-notifications` | Disable sound notifications (enabled by default when not in execute mode) |
| `--settings-file <value>` | Custom settings file path (overrides the default location) |
| `--log-level <value>` | Set log level (error, warn, info, debug, audit) |
| `--log-file <value>` | Set log file location (overrides the default location) |
| `--dangerously-allow-all` | Disable all command confirmation prompts (agent will execute all commands without asking) |
| `--mcp-config <value>` | JSON configuration or file path for MCP servers to merge with existing settings |
| `--try-gpt5` | Try GPT-5 as the primary agent model (limited time; see `https://ampcode.com/news/`gpt-5) |
| `-x, --execute [message]` | Use execute mode, optionally with user message. In execute mode, agent will execute provided prompt (either as argument, or via stdin). Only last assistant message is printed. Enabled automatically when redirecting stdout. |
| Option | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| --visibility <visibility> | Set thread visibility (private, public, workspace, group) |
| -V, --version | output the version number |
| --notifications | Enable sound notifications (enabled by default when not in execute mode) |
| --no-notifications | Disable sound notifications (enabled by default when not in execute mode) |
| --settings-file <value> | Custom settings file path (overrides the default location) |
| --log-level <value> | Set log level (error, warn, info, debug, audit) |
| --log-file <value> | Set log file location (overrides the default location) |
| --dangerously-allow-all | Disable all command confirmation prompts (agent will execute all commands without asking) |
| --mcp-config <value> | JSON configuration or file path for MCP servers to merge with existing settings |
| --jetbrains | Enable JetBrains integration. When enabled, Amp automatically includes your open JetBrains file and text selection with every message. |
| --no-jetbrains | Disable JetBrains integration. |
| --ide | Enable IDE connection (default). When enabled, Amp automatically includes your open IDE's file and text selection with every message. |
| --no-ide | Disable IDE connection. |
| --stream-json | When used with --execute, output in Claude Code compatible stream JSON format instead of plain text. |
| --stream-json-input | Read JSON Lines user messages from stdin. Requires both --execute and --stream-json. |
| -x, --execute \[message\] | Use execute mode, optionally with user message. In execute mode, agent will execute provided prompt (either as argument, or via stdin). Only last assistant message is printed. Enabled automatically when redirecting stdout. |

## Commands

Amp CLI includes several subcommands for enhanced functionality:

| Command | Description |
| --------------------- | ----------- |
| `logout` | Log out by removing stored API key |
| `login` | Log in to Amp |
| `threads` | Manage threads |
| `threads new` | Create a new thread |
| `threads continue` | Continue an existing thread |
| `threads fork` | Fork an existing thread |
| `threads list` | List all threads |
| `threads share` | Share a thread |
| `threads compact` | Compact a thread |
| `tools` | Tool management commands |
| `tools list` | List all active tools (including MCP tools) |
| `tools show` | Show details about an active tool |
| `permissions` | Manage permissions |
| `permissions list` | List permissions |
| `permissions test` | Test permissions |
| `permissions edit` | Edit permissions |
| `permissions add` | Add permission rule |

| `doctor` | Generate support bundle |
| `update` | Update Amp CLI |
| Command | Description |
| ------------------ | -------------------------------------------------------- |
| `logout` | Log out by removing stored API key |
| `login` | Log in to Amp |
| `threads` | Manage threads |
| `threads new` | Create a new thread |
| `threads continue` | Continue an existing thread |
| `threads fork` | Fork an existing thread |
| `threads list` | List all threads |
| `threads share` | Share a thread |
| `threads compact` | Compact a thread |
| `tools` | Tool management commands |
| `tools list` | List all active tools (including MCP tools) |
| `tools show` | Show details about an active tool |
| `tools make` | Sets up a skeleton tool in your toolbox |
| `tools use` | Invoke a tool with arguments or JSON input from stdin |
| `permissions` | Manage permissions |
| `permissions list` | List permissions |
| `permissions test` | Test permissions |
| `permissions edit` | Edit permissions |
| `permissions add` | Add permission rule |
| `mcp` | Manage MCP servers |
| `mcp add` | Add an MCP server configuration |
| `mcp remove` | Remove an MCP server configuration |
| `mcp doctor` | Check MCP server status |
| `connect` | Connect CLI to web interface for multi-thread management |
| `doctor` | Generate support bundle |
| `update` | Update Amp CLI |

## Environment Variables

| Variable | Description |
| ------------------- | ----------- |
| `AMP_API_KEY` | API key for Amp (see `https://ampcode.com/settings`) |
| `AMP_URL` | URL for the Amp service (default is `https://ampcode.com/`) |
| `AMP_LOG_LEVEL` | Set log level (can also use --log-level) |
| `AMP_LOG_FILE` | Set log file location (can also use --log-file) |
| `AMP_SETTINGS_FILE` | Set settings file path (can also use --settings-file, default: ~/.config/amp/settings.json) |
| Variable | Description |
| ----------------- | ------------------------------------------------------------------------------------------- |
| AMP_API_KEY | API key for Amp (see https://ampcode.com/settings) |
| AMP_URL | URL for the Amp service (default is https://ampcode.com/) |
| AMP_LOG_LEVEL | Set log level (can also use --log-level) |
| AMP_LOG_FILE | Set log file location (can also use --log-file) |
| AMP_SETTINGS_FILE | Set settings file path (can also use --settings-file, default: ~/.config/amp/settings.json) |

## Examples

Expand Down Expand Up @@ -249,6 +260,24 @@ Execute a prompt from a file and store final assistant message output in a file
amp < prompt.txt > output.txt
```

Add an MCP server with a local command:

```bash
amp mcp add context7 -- npx -y @upstash/context7-mcp
```

Add an MCP server with environment variables:

```bash
amp mcp add postgres --env PGUSER=orb -- npx -y @modelcontextprotocol/server-postgres postgresql://localhost/orbing
```

Add a remote MCP server:

```bash
amp mcp add hugging-face https://huggingface.co/mcp
```

## Configuration

Amp can be configured using a JSON settings file located at `~/.config/amp/settings.json`. All settings use the "amp." prefix.
Expand All @@ -268,26 +297,21 @@ Sample configuration:
]
}
},
"amp.tools.disable": [
"browser_navigate",
"builtin:edit_file"
],
"amp.tools.disable": ["browser_navigate", "builtin:edit_file"],
"amp.permissions": [
{
"tool": "Bash",
"action": "ask",
"matches": {
"cmd": [
"git push*",
"git commit*"
]
"cmd": ["git push*", "git commit*"]
}
}
],
"amp.guardedFiles.allowlist": [],
"amp.dangerouslyAllowAll": false,
"amp.git.commit.coauthor.enabled": true,
"amp.git.commit.ampThread.enabled": true
"amp.git.commit.ampThread.enabled": true,
"amp.updates.mode": "auto"
}
```

Expand All @@ -303,6 +327,7 @@ Sample configuration:
- **`amp.git.commit.coauthor.enabled`**: Enable adding Amp as co-author in git commits
- **`amp.git.commit.ampThread.enabled`**: Enable adding Amp-Thread trailer in git commits
- **`amp.proxy`**: Proxy URL used for both HTTP and HTTPS requests to the Amp server
- **`amp.updates.mode`**: Control update checking behavior: "warn" shows update notifications, "disabled" turns off checking, "auto" automatically runs update.

## Tool Usage

Expand Down Expand Up @@ -372,4 +397,4 @@ If you see an "Out of free credits" message, visit [ampcode.com/settings](https:

## Last updated

2025-09-05
2025-10-16
Loading