---
title: "CLI Reference"
source: https://docs.autohand.ai/working-with-autohand-code/cli-reference
---

# CLI Reference

Complete reference for all CLI options, slash commands, tools, and keyboard shortcuts available in the Autohand Code CLI.

## CLI options

``` bash
autohand [options]
autohand resume <sessionId> [options]
```

| Option | Description |
|---|---|
| [prompt] | Run a single instruction in command mode (same as -p) |
| -p, --prompt [text] | Run a single instruction in command mode; with piped stdin, combines stdin and prompt text |
| --path <path> | Workspace path to operate in |
| --new | Start a new session instead of auto-resuming the last session in the workspace |
| --session <session-id> | Run command mode against a specific saved session |
| --resume | Resume the last session for the current workspace in command mode |
| -y, --yes | Auto-confirm risky actions |
| -m, --model <model> | Override the configured LLM model |
| --config <path> | Path to config file |
| --temperature <value> | Sampling temperature for the model |
| --dry-run | Preview actions without applying changes |
| --unrestricted | Run without approval prompts |
| --restricted | Deny all dangerous operations |
| --tools <list> | Limit loaded tools for the run; pass a comma-separated list or an empty value for conversation-only mode |
| --auto-skill | Auto-generate skills based on project structure |
| --learn | Run skill advisor non-interactively (analyze project and install recommended skills) |
| --learn-update | Re-analyze project and regenerate outdated LLM-generated skills |
| -c, --auto-commit | Auto-commit changes after completing tasks (runs lint and test first) |
| -v, --version | Show version number |
| -d, --debug | Enable verbose debug output |
| --verbose | Print progress details to stderr for scripts and CI logs |
| --thinking [level] | Set reasoning depth (none, normal, extended) |
| --patch | Generate a git-compatible patch file |
| --output <file> | Write patch output to a specific file |
| --output-format <format> | Set command-mode output format: text, json, or stream-json |
| --json | Emit newline-delimited JSON events for composable scripts |
| --mode <mode> | Run mode: interactive, rpc, or acp |
| --acp | Shorthand for --mode acp (Agent Client Protocol over stdio) |
| --goal [input] | Experimental: run /goal non-interactively when slash_goal is enabled; omitted input prints goal status |
| --teammate-mode <mode> | Team display mode: auto, in-process, or tmux |
| --worktree [name] | Run session in isolated git worktree (optional branch name) |
| --tmux | Launch in a dedicated tmux session (implies --worktree) |
| --setup | Run the setup wizard |
| --about | Show version and system information |
| --add-dir <path...> | Add additional directories to the workspace |
| --display-language <locale> | Set the display language (e.g., en, es, fr, ja) |
| --cc, --context-compact | Enable context compaction |
| --no-cc, --no-context-compact | Disable context compaction |
| --search-engine <provider> | Set web search provider (browser-profile, exa, google, brave, duckduckgo, parallel) |
| --sys-prompt <value> | Replace the default system prompt (accepts text or file path) |
| --append-sys-prompt <value> | Append to the default system prompt (accepts text or file path) |
| --yolo [pattern] | Auto-approve commands matching pattern without confirmation |
| --timeout <seconds> | Set timeout for auto-approved commands in YOLO mode |
| --skill-install [name] | Install a community skill |
| --project | Install skill at project level instead of global |
| --sync-settings [bool] | Toggle settings sync across devices |
| --login | Authenticate with the Autohand service |
| --logout | Sign out from the Autohand service |
| --settings | Configure Autohand settings and exit |
| --permissions | Display current permissions and exit |
| --feedback | Submit feedback |
| --chrome | Enable Chrome browser integration (same as /chrome) |
| --no-chrome | Disable Chrome browser integration |
| --interactive-on-complete | After auto-mode ends, hand off to interactive mode (TTY only) |

### Auto-mode options

Options for autonomous development loops. See the [Auto-mode guide](/docs/guides/auto-mode.html) for details.

| Option | Description | Default |
|---|---|---|
| --auto-mode [prompt] | Enable interactive auto-mode, or start a standalone loop with an inline task | - |
| --max-iterations <n> | Maximum loop iterations | 50 |
| --completion-promise <text> | Text marker signaling task completion | "DONE" |
| --no-worktree | Disable git worktree isolation | false |
| --checkpoint-interval <n> | Git commit every N iterations | 5 |
| --max-runtime <m> | Maximum runtime in minutes | 120 |
| --max-cost <d> | Maximum API cost in dollars | 10 |

### Headless output and sessions

Command mode is designed for scripts, cron jobs, CI, and remote runners. Use text output for human-readable summaries, JSON for one result object, and stream-json for long-running jobs where progress should appear incrementally.

| Command | Use case |
|---|---|
| autohand -p "review this repo" --restricted | Read-only analysis with no dangerous operations |
| autohand -p "run tests and fix failures" --output-format stream-json | Stream progress into logs or a remote job UI |
| autohand -p "summarize this diff" --output-format json | Capture a single machine-readable result |
| autohand -p "continue the release task" --session <id> | Continue a known saved session from automation |
| autohand -p "start a clean review" --new | Force a fresh session for repeatable jobs |

### Subcommands

Standalone subcommands that run outside interactive mode.

| Command | Description |
|---|---|
| autohand resume <sessionId> | Resume a previous session |
| autohand login | Sign in to your Autohand account |
| autohand logout | Sign out of your Autohand account |
| autohand config | Configure Autohand settings (same as /settings) |
| autohand sessions | List saved sessions (filter with --project) |
| autohand init | Create an AGENTS.md file in the workspace |
| autohand update [--check] | Check for updates and install if available |
| autohand upgrade [--check] | Alias for update |
| autohand import [source] | Import data from other coding agents; supports --all, --categories, --dry-run, and --retry-failed |
| autohand completion <shell> | Generate shell completion scripts (bash, zsh, fish) |
| autohand mcp | Manage MCP (Model Context Protocol) servers |

### MCP subcommands

Manage MCP servers from outside interactive mode.

| Command | Description |
|---|---|
| autohand mcp add <name> <target> [args...] | Add an MCP server to config and auto-connect it next session |
| autohand mcp add -t <transport> -s <scope> <name> <target> | Add with transport stdio, http, or sse and scope user or project |
| autohand mcp list [-s <scope>] | List configured MCP servers |
| autohand mcp remove <name> [-s <scope>] | Remove an MCP server from config |
| autohand mcp install [server-name] [-s <scope>] | Browse and install community MCP servers |

## Slash commands

Type `/` to see available commands. These work inside an interactive session:

| Command | Description |
|---|---|
| /help or /? | Show available commands and tips |
| /model | Configure or switch LLM providers |
| /session | Show current session details |
| /sessions | List past sessions |
| /resume | Resume a previous session by ID |
| /new | Start a fresh conversation |
| /clear | Clear the conversation with automatic memory extraction |
| /undo | Revert git changes and remove last turn |
| /memory | View stored project and user memories |
| /init | Create an AGENTS.md file |
| /agents | List available sub-agents |
| /agents new or /agents-new | Create a new sub-agent via wizard |
| /skills | List available skills |
| /skills use <name> | Activate a skill for the current session |
| /skills info <name> | Show details about a specific skill |
| /skills search | Search for skills in the community registry |
| /skills trending | Show trending community skills |
| /skills install | Install a community skill from the registry |
| /skills remove <name> | Remove an installed skill |
| /skills deactivate <name> | Deactivate a skill for the current session |
| /skills feedback <name> | Send skill feedback |
| /skills new or /skills-new | Create a new custom skill interactively |
| /learn | Get LLM-powered skill recommendations for your project |
| /learn deep | Deep-analyze the project for better skill matching |
| /learn update [deep] | Regenerate stale LLM-generated skills |
| /feedback | Send feedback with environment details |
| /formatters | List available code formatters |
| /lint | List available code linters |
| /completion | Generate shell completion scripts |
| /export | Export session to markdown, JSON, or HTML |
| /quit | Exit the session |
| /mcp | Interactive MCP server manager (toggle enable/disable) |
| /mcp connect <name> | Connect to a configured MCP server |
| /mcp disconnect <name> | Disconnect from an MCP server |
| /mcp add | Add custom server or browse community registry |
| /mcp list | List tools from connected MCP servers |
| /mcp tools | Alias for listing available MCP tools |
| /mcp remove <name> | Remove an MCP server |
| /mcp install | Install a new MCP server from the registry |
| /cc | Toggle context compaction on or off |
| /search | Configure web search provider |
| /sync | Configure settings sync |
| /settings | Configure application settings (ui, agent, permissions, network, telemetry) |
| /theme | Change terminal color theme |
| /plan | Toggle plan mode (read-only planning before execution) |
| /goal | Experimental persistent goals, queues, budgets, templates, and status; requires slash_goal |
| /status | Show current session status and statistics |
| /login | Authenticate with the Autohand service |
| /logout | Sign out from the Autohand service |
| /permissions | Inspect current permission settings |
| /hooks | Manage project hooks |
| /add-dir <path...> | Add directories to the current workspace scope |
| /language | Change the display language |
| /history | Browse session history |
| /about | Show version and system information |
| /ide | Show IDE integration info |
| /share | Share the current session |
| /repeat [interval] <prompt> | Schedule a recurring prompt at a fixed interval |
| /repeat list | Show active recurring jobs |
| /repeat cancel <id> | Cancel a recurring job |
| /repeat help | Show repeat usage and examples |
| /team | Manage agent teams |
| /team create | Create a new team |
| /team status | Show team status |
| /team shutdown | Shut down all teammates |
| /tasks | List and manage team tasks |
| /message | Send a direct message to a teammate |
| /chrome | Continue session in Chrome extension |
| /chrome disconnect | Disconnect the Chrome bridge |
| /import [source] | Import data from other coding agents |
| /review | Run a staff-level code review with actionable findings |
| /pr-review | Review a pull request using gh metadata and diff context |
| /setup | Run the setup wizard |
| /yolo | Toggle YOLO mode for auto-approving actions |
| /tools | List, inspect, disable, rename, or delete persisted meta-tools |

### Settings editor

`/settings` opens the interactive settings editor in the terminal. It organizes configuration into UI, Agent, Permissions, Network, Telemetry, Auto-mode, Teams, and Search categories, then saves changes to `~/.autohand/config.json`.

Use the editor for common changes such as theme, display language, provider redirects, permission defaults, retry behavior, telemetry, team display mode, and search provider. Use `--config <path>` or `AUTOHAND_CONFIG` when automation needs a dedicated config file.

### Goal commands

`/goal` is an experimental durable goal surface behind the `slash_goal` feature flag. Enable it with `/features enable slash_goal` before using the slash command, `--goal`, JSON-RPC goal methods, ACP command metadata, or the goal tools.

| Command | Description |
|---|---|
| /goal | Show the active goal and queued goals |
| /goal <objective> | Create a persistent active goal |
| /goal queue <objective> | Add a goal to the FIFO queue without replacing the active goal |
| /goal pause | Pause the active goal |
| /goal resume | Resume a paused goal, or start the next queued goal when no active goal exists |
| /goal complete | Mark the active goal complete |
| /goal clear | Clear the active goal |
| /goal templates | List reusable templates from .pi-goals/ and .ai/.pi-goals/ |
| autohand --goal [input] | Run the same goal surface outside interactive mode |

### Auto-mode commands

| Command | Description |
|---|---|
| /automode <prompt> | Start auto-mode with a task |
| /automode on | Enable interactive auto-mode for this session |
| /automode off | Disable interactive auto-mode for this session |
| /automode status | Show current loop state |
| /automode pause | Pause the loop |
| /automode resume | Resume paused loop |
| /automode cancel | Cancel the loop |
| /automode help | Show auto-mode help |

## Interactive input

Autohand accepts several terminal-native inputs in addition to normal prompts and slash commands.

| Input | Behavior |
|---|---|
| ! | Run a shell command directly without asking the model, such as ! git status or ! npm test |
| @ | Open file and directory mention autocomplete |
| # | Save a project or user memory for future sessions |
| / | Open slash command suggestions |
| Shift+Tab | Toggle plan mode when supported by the terminal |
| Esc | Cancel the current operation or close the active picker |
| Ctrl+C | Warn on first press during active work; press again to force exit |
| Large paste | Compact pasted content into a paste indicator while still sending the full content to the model on submit |

## File mentions

Type `@` followed by a filename to include file context in your prompt. Autohand shows an autocomplete palette with your workspace files.

``` bash
# Include a specific file
"Fix the bug in @src/utils/parser.ts"

# Mention multiple files
"Compare @package.json with @package-lock.json"
```

Use arrow keys to navigate suggestions and Tab to autocomplete.

## Memory

Store context for reuse across sessions by typing `#` followed by your memory content:

``` bash
# always use TypeScript strict mode for this project
# prefer functional components over class components
# run npm test before committing
```

When you save a memory, Autohand asks where to store it:

-   **Project level**: Saved to `.autohand/memory/` in your repo. Shared with your team via version control.
-   **User level**: Saved to `~/.autohand/memory/`. Personal preferences that apply across all projects.

Autohand detects similar existing memories and offers to update them instead of creating duplicates. View all stored memories with `/memory`.

## Configuration lookup

Autohand loads configuration from the first available source in this order:

1.  `AUTOHAND_CONFIG` environment variable or the `--config` flag for an explicit path
2.  `~/.autohand/config.toml`
3.  `~/.autohand/config.yaml`
4.  `~/.autohand/config.yml`
5.  `~/.autohand/config.json`

Use a dedicated config file for CI, cron, VPS, Docker, or webhook runners so automation does not inherit personal interactive settings by accident.

### Local project permissions

Project-level approvals can be saved to `.autohand/settings.local.json`. Local permissions take priority over global settings, which is useful when a trusted repository can auto-approve narrow commands while other projects remain interactive.

``` json
{
  "permissions": {
    "allow": ["run_command:npm test", "run_command:npm run lint"],
    "deny": ["run_command:rm *", "delete_path:*"]
  }
}
```

## Tools

Autohand has access to a comprehensive set of tools for working with your codebase:

### File operations

-   `read_file`: Read file contents
-   `write_file`: Write full contents to a file
-   `notebook_edit`: Edit Jupyter notebook cells by index or cell ID
-   `append_file`: Append text to a file
-   `apply_patch`: Apply a unified diff patch
-   `search_replace`: Apply exact SEARCH/REPLACE blocks
-   `create_directory`: Create directories
-   `delete_path`: Remove files or directories (requires approval)
-   `rename_path`: Rename or move files
-   `copy_path`: Copy files or directories
-   `list_tree`: Show directory structure
-   `file_stats`: Get file metadata
-   `checksum`: Compute file checksums

### Search

-   `fff_grep`: Content search with frecency ranking, definition detection, and ripgrep fallback
-   `fff_find`: Path and filename search with frecency ranking and ripgrep fallback
-   `tool_search`: Search built-in and meta tools by capability, name, or description

### Git operations

-   `git_status`, `git_diff`, `git_log`: View repository state
-   `git_list_untracked`, `git_diff_range`, `git_apply_patch`: Inspect untracked files, staged changes, ranges, and patches
-   `git_add`, `git_commit`, `git_reset`, `auto_commit`: Stage, reset, and commit changes
-   `git_branch`, `git_switch`, `git_checkout`: Branch management
-   `git_stash`, `git_stash_list`, `git_stash_pop`, `git_stash_apply`, `git_stash_drop`: Stash operations
-   `git_merge`, `git_merge_abort`, `git_rebase`, `git_rebase_abort`, `git_rebase_continue`, `git_rebase_skip`: Integration and conflict workflows
-   `git_cherry_pick`, `git_cherry_pick_abort`, `git_cherry_pick_continue`: Cherry-pick workflows
-   `git_fetch`, `git_pull`, `git_push`: Remote operations
-   `git_worktree_*`: Advanced worktree management

### Development

-   `run_command`: Execute shell commands (requires approval)
-   `shell`: Execute shell commands with live TUI output
-   `custom_command`: Define reusable commands
-   `add_dependency`: Add npm packages
-   `remove_dependency`: Remove npm packages
-   `format_file`: Format with prettier, black, rustfmt, etc.
-   `code_review`: Run a staff-engineer-level code review

### Planning

-   `plan`: Capture planning notes
-   `exit_plan_mode`: Present a plan for approval and exit planning
-   `todo_write`: Create structured task lists
-   `tools_registry`: List all available tools
-   `ask_followup_question`: Ask the user for clarification in interactive or plan mode

### Memory and skills

-   `save_memory`, `recall_memory`: Store and retrieve reusable project or user context
-   `skill`: Invoke an installed skill
-   `find_agent_skills`, `install_agent_skill`: Discover and install agent skills
-   `create_meta_tool`: Persist a reusable meta-tool

### Agents, teams, and tasks

-   `delegate_task`, `delegate_parallel`: Send work to one or more sub-agents
-   `create_team`, `add_teammate`, `team_status`, `send_team_message`: Manage collaborative agent teams
-   `create_task`, `task_get`, `task_list`, `task_update`, `task_stop`, `task_output`: Track and inspect team tasks
-   `enter_worktree`, `exit_worktree`: Move between isolated worktree contexts

### Web and browser

-   `web_search`, `fetch_url`, `package_info`, `web_repo`: Search the web, fetch pages, inspect packages, and look up repository metadata
-   `browser_screenshot`, `browser_click`, `browser_type`, `browser_navigate`, `browser_scroll`: Drive the connected Chrome tab
-   `browser_find_element`, `browser_get_element`, `browser_wait_for_element`, `browser_press_key`: Inspect and interact with page elements
-   `browser_get_page_context`, `browser_read_network`, `browser_read_console`, `browser_execute_js`: Debug and extract browser context
-   `browser_get_tabs`, `browser_get_tab_groups`: Inspect open tabs and tab groups

### Scheduling and workspace access

-   `cron_create`, `cron_delete`, `list_schedules`, `cancel_schedule`: Create and manage recurring work
-   `sleep`: Pause execution for a duration
-   `request_directory_access`: Request permission to work outside currently allowed directories
-   `project_tracker`: Track project progress

## Sub-agents

Define specialized sub-agents in `~/.autohand/agents/` as markdown files. Each agent has a name, description, optional model override, and allowed tools.

View available agents with `/agents`. Create new ones with `/agents new` or `/agents-new`.

Autohand can delegate tasks to sub-agents:

-   `delegate_task`: Send a task to a specific sub-agent
-   `delegate_parallel`: Run up to 5 sub-agents in parallel

## Permissions

Autohand operates in three permission modes:

-   **Interactive** (default): Asks for confirmation before destructive operations like deleting files or running shell commands.
-   **Unrestricted** (`--unrestricted`): No approval prompts. Use with caution.
-   **Restricted** (`--restricted`): Automatically denies all dangerous operations.

Configure fine-grained permissions in your config file:

``` json
{
  "workspace": {
    "allowDangerousOps": false,
    "allowPatterns": ["run_command:npm *", "run_command:bun *"],
    "denyPatterns": ["run_command:rm -rf *", "run_command:sudo *"]
  }
}
```

## Sessions

Sessions are automatically saved to `~/.autohand/sessions/`. Each session tracks:

-   Conversation history
-   Tool outputs and agent reasoning
-   Project path and model used
-   Timestamps and message counts

Resume any session later:

``` bash
# From the CLI
autohand resume abc123

# Inside an interactive session
/resume abc123

# List all sessions
/sessions
```

Export sessions for sharing or archiving:

``` bash
/export markdown ./session-report.md
/export json ./session-data.json
/export html ./session-report.html
```

## AGENTS.md

Create an `AGENTS.md` file in your project root to guide Autohand's behavior. Use `/init` to generate a template.

Include information like:

-   Framework and build commands
-   Testing requirements
-   Code style preferences
-   Project-specific constraints

Autohand reads this file automatically and follows its guidelines.

## Keyboard shortcuts

| Key | Action |
|---|---|
| ESC | Cancel current operation |
| Ctrl+C (twice) | Force exit |
| Tab | Autocomplete file paths |
| Shift+Tab | Toggle plan mode |
| Up Down | Navigate suggestions |
| / | Open slash command menu |
| @ | Open file mention palette |

## YOLO mode

YOLO mode auto-approves tool calls without confirmation prompts. Use it to skip repetitive approvals for trusted operations.

``` bash
# Auto-approve all commands
autohand --yolo

# Auto-approve with pattern matching
autohand --yolo "allow:npm *,deny:rm *"

# Set a timeout for auto-approved commands
autohand --yolo --timeout 30
```

Patterns support `allow:` and `deny:` prefixes with glob matching. Deny rules take precedence over allow rules.

**Tip:** Combine `--yolo` with `--timeout` to limit how long auto-approved commands can run before being killed.

## Context compaction

Context compaction automatically compresses conversation history when it approaches the model's context window limit. This lets you work in long sessions without losing important context.

``` bash
# Enable via CLI flag
autohand --cc

# Disable via CLI flag
autohand --no-cc

# Toggle during a session
/cc
```

Compaction triggers at tiered thresholds:

-   **70%** — Light compression, removing redundant tool outputs
-   **80%** — Medium compression, summarizing older conversation turns
-   **90%** — Aggressive compression, keeping only essential context

The status bar shows `[CC: ON]` or `[CC: OFF]` to indicate the current state.

## Thinking and reasoning

Control how much reasoning the model performs before responding. Extended thinking produces better results for complex tasks but uses more tokens.

``` bash
# No extended thinking
autohand --thinking none

# Normal reasoning (default)
autohand --thinking normal

# Extended deep reasoning
autohand --thinking extended
```

You can also enable extended thinking by default in your settings:

``` json
{
  "alwaysThinkingEnabled": true
}
```

## Frequently asked questions

### What are the most common Autohand Code CLI flags?

The most used flags are --prompt (-p) for single instructions, --model to override the AI model, --yes (-y) to auto-confirm actions, --thinking to set reasoning depth, --auto-mode for autonomous loops, and --yolo for auto-approving trusted commands. Run autohand --help for the full list.

### How do I run Autohand Code CLI in auto-mode?

Start auto-mode with autohand --auto-mode 'your task description' from the command line, or type /automode inside an interactive session. Set limits with --max-iterations, --max-cost, and --max-runtime. Auto-mode runs in a git worktree by default for safety.

### How do I change the AI model in Autohand?

Use the --model flag when starting a session: autohand --model claude-4-sonnet. Inside a running session, type /model to see available models and switch. Configure your default model in ~/.autohand/config.json under the model field.

### What is the difference between --unrestricted and --yolo?

The --unrestricted flag skips all approval prompts for every operation. The --yolo flag gives finer control with pattern matching: --yolo 'allow:npm \*,deny:rm \*' auto-approves npm commands while still blocking destructive rm commands. Use --yolo for targeted automation and --unrestricted only when you trust every action.