AI Doer CLI — User Guide

The AI Doer CLI (aidoer) is a terminal client for the AI Doer AI agent. It runs the same agent engine that powers the AI Doer Editor and the VS Code extension — the difference is that the CLI embeds the engine in-process (as the mcp_universal Rust crate) and drives it directly, so there's no local HTTP server to manage.

Scope note. The CLI's own source (argument parsing, terminal rendering) lives in the separate aidoer repository. This repo (getaibd-editor) contains the shared engine (agent/) that the CLI vendors as engine/. So everything in this guide about agent behavior, modes, tools, and project configuration is authoritative and identical across all three products; only the exact CLI command flags are defined in the CLI repo and may differ slightly from the examples below.

Engine internals are documented in the source repository.

1. What the CLI is for

The CLI lets you point the AI Doer agent at a project from your terminal and:

• Ask questions about a codebase.
• Have the agent implement features, fix bugs, and refactor across files.
• Run and review shell commands with approval gates.
• Plan work before executing it.
• Review code changes.

Because the engine is embedded in-process, the CLI is a good place to validate agent behavior quickly and to script agent runs.

2. Installing

Install from the aidoer repository/release channel (see that project's README for the current install command). Once installed, run it from within (or pointed at) a project directory.

getaibd-cli            # start in the current directory

The CLI is scoped to a single project root (the directory you run it in, or one you pass explicitly). Memory and context are keyed to that root.

3. Authentication & the free tier

• Free tier ("Auto") works out of the box via the free qwen-flash-backed model.
• API key: set GETAIBD_API_KEY to use premium models and lift the free-tier limits. The base URL defaults to https://getaibd.com/v1/api and can be overridden with GETAIBD_BASE_URL.

The CLI uses a login-based trial gate rather than the editor/VS anonymous device fingerprint. Consult the CLI repo for the login flow.

4. Basic usage

Typical patterns (exact flags come from the CLI repo):

# Interactive session in the current project
getaibd-cli

# One-shot prompt
getaibd-cli "explain how authentication works in this repo"

# Point at a specific project
getaibd-cli --project /path/to/repo "add a health check endpoint"

During a run the CLI streams the agent's activity to your terminal:

• Thinking / planning — the model's reasoning.
• Tool calls — e.g. reading a file, searching, running a command.
• Answer text — the model's response, streamed.
• File edits — a summary of files the agent changed (review/revert per the CLI's UI).
• Completion — when the run finishes.

5. Modes

The agent supports the same modes everywhere. Select the mode appropriate to your task:

Each mode has its own system prompt and iteration budget, and Plan/Ask/Reviewer restrict the toolset to read-only operations (plus plan writing in Plan mode).

6. Approvals & command safety

The agent asks before running shell commands and using certain tools. In the CLI these are resolved through in-process approval gates:

• Approve / deny each request, or set a tool to always-allow for the session.
• Dangerous commands (e.g. sudo, rm, curl, wget, ssh, raw shells) always require explicit approval — even if the tool is otherwise allowed.

You can codify a policy so you're not prompted for routine commands — see permissions.json.

7. What the agent can do (tools)

The agent has a rich toolset (identical across editor/CLI/VS). Highlights:

Files & editing

• read_file, write_file, patch_file, list_directory, search_files, move_file, delete_file.

Search & code intelligence

• search_code — one search tool that auto-routes between exact (ripgrep), symbol, and semantic search.
• semantic_search, find_symbol, find_references, document_symbols.
• explore — a read-only sub-agent that scopes out "where does X live" without cluttering the main run.

Shell & environment

• run_command (with background support for long-running/dev-server commands), read_terminal, manage_env.

Git & GitHub

• git_status, git_diff (supports ref / base..head), git_log (path/author filters), git_show, git_blame, git_branch, git_checkout, git_add, git_commit, git_reset, git_push.
• github_pr_list, github_pr_create, github_pr_checkout.

Worktrees

• worktree_list, worktree_create, worktree_remove (with optional per-project setup commands from worktrees.json).

Web

• web_fetch — fetches any URL and understands GitHub PRs, issues, files, and commits, public or private (prefers a local clone using your SSH creds, falls back to the gh CLI / GH_TOKEN).
• web_search (needs a AI Doer key).

Planning & completion

• update_plan, write_plan (Plan mode), attempt_completion.

External tools

• Any MCP servers you configure in .getaibd/mcp.json are exposed as tools.

Large tool outputs (web_fetch, git_diff, git_show, git_blame) are stashed to .getaibd/tmp/ and referenced by path so they don't bloat the conversation context.

8. Project configuration (.getaibd/)

Drop a .getaibd/ folder in your project (or ~/.getaibd/ for global defaults) to guide the agent. These files are shared across all AI Doer clients:

AGENTS.md — project instructions

Free-form markdown rules the agent always reads for this project. Merged with the built-in baseline guidance.

rules/*.md — scoped rules

Markdown files with front matter (description, globs, alwaysApply) that apply conditionally.

permissions.json — command/tool policy

{
  "mode": "auto-review",
  "allow": ["git status", "cargo *", "read_file"],
  "ask": ["git push*", "*sudo*"],
  "deny": ["rm -rf /*"],
  "protect": { "file_deletion": true, "external_files": true }
}

mode is one of auto-review, allowlist, or run-everything. Project rules override global ones.

sandbox.json — opt-in command sandboxing

{
  "enabled": false,
  "writable_paths": ["~/.cargo"]
}

When enabled, run_command is wrapped in an OS sandbox — sandbox-exec (macOS Seatbelt) or bwrap (Linux) — restricting writes to the workspace, /tmp, and your writable_paths.

worktrees.json — worktree setup

{
  "setup-worktree": ["npm install"],
  "setup-worktree-unix": ["./setup.sh"],
  "setup-worktree-windows": ["setup.bat"]
}

mcp.json — external MCP servers

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "env": { "KEY": "value" }
    }
  }
}

MEMORY.md — durable project notes

Long-lived facts the agent should remember about the project.

9. Memory & codebase awareness

The agent maintains a per-project index so it can find relevant code:

• On startup it indexes important files and incrementally re-indexes changes (via a Merkle tree over file hashes).
• Retrieval is hybrid (semantic embeddings + keyword search).
• Indexing and memory writes are paused when disk space is low (below ~1 GiB) so a full disk doesn't wedge the engine.

The index lives outside your project (see §12), so it never clutters your working tree.

10. Models & reasoning

• Auto (free) is the default. With GETAIBD_API_KEY set you can use premium models.
• Reasoning-capable models accept a reasoning effort (low / medium / high) for harder problems.
• The pipeline uses a cheaper/faster model for triage, planning, and exploration, reserving your chosen model for the actual work — keeping simple tasks fast and complex ones structured.

11. Environment variables

12. Data & config locations

The per-project slug is a stable hash of the canonical project root.

13. Troubleshooting

The agent keeps asking to run the same commands. Add them to allow in .getaibd/permissions.json, or choose "always allow" when prompted. Dangerous commands always re-prompt by design.

A private GitHub PR/issue won't fetch. web_fetch prefers a local clone via your SSH credentials, then falls back to the gh CLI / GH_TOKEN. Make sure one of those has access to the repo.

Indexing seems disabled. Free disk space is probably below the threshold — indexing and memory writes pause until you free space (or raise GETAIBD_MIN_FREE_DISK_MB).

A long-running command "hangs" the run. Long-running / dev-server commands are detached to the background; the run continues. Inspect output via the CLI's terminal view / read_terminal.

I want the exact CLI flags. Command-line flags, subcommands, and the interactive UI are defined in the aidoer repository; run getaibd-cli --help for the authoritative list.