CLI Reference

CLI options

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

Auto-mode options

Options for autonomous development loops. See the Auto-mode guide for details.

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.

Subcommands

Standalone subcommands that run outside interactive mode.

MCP subcommands

Manage MCP servers from outside interactive mode.

Slash commands

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

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.

Auto-mode commands

Interactive input

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

File mentions

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

# 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:

# 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.

{
  "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:

{
  "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:

# From the CLI
autohand resume abc123

# Inside an interactive session
/resume abc123

# List all sessions
/sessions

Export sessions for sharing or archiving:

/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

YOLO mode

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

# 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.

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.

# 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.

# 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:

{
  "alwaysThinkingEnabled": true
}

Frequently asked questions