Aider Cheat Sheet - Commands and Workflows

Aider is a git-native AI pair programming tool that runs in your terminal. The CLI exposes more than 80 flags, four chat modes, 40+ slash commands, and a YAML config schema with around 100 keys. The official docs split that surface across many pages. This cheat sheet condenses everything into a single reference, with every command tested on Ubuntu 26.04 LTS using Aider 0.86.2.

Original content from computingforgeeks.com - post 167356

If you came from the Aider setup guide and want one page to keep open while you work, this is it.

Verified working: May 2026 with Aider 0.86.2 on Ubuntu 26.04 LTS, tested with Claude Sonnet 4.6, GPT-5, and Gemini 2.5 Pro.

Quick install reminder

The recommended path on Linux and macOS is the aider-install bootstrapper, which pins a working Python and pulls Aider into an isolated virtualenv:

pipx install aider-install
aider-install
aider --version

aider 0.86.2

For provider keys, .env layout, and Windows install paths see the dedicated Aider AI pair programming setup walkthrough.

Where Aider stores config

Aider reads four files in priority order. Top of the list wins:

CLI flags: aider --model claude-sonnet-4-6
Environment variables: AIDER_MODEL, AIDER_OPENAI_API_KEY, every flag has an env var twin
Config file: .aider.conf.yml (searched in git root, then cwd, then $HOME)
Built-in defaults

API keys belong in a separate .env file (default location: git root):

# .env (in your repo root, gitignored)
ANTHROPIC_API_KEY=sk-ant-api03-...
OPENAI_API_KEY=sk-proj-...
GEMINI_API_KEY=aiza...
DEEPSEEK_API_KEY=sk-...

And a starter .aider.conf.yml looks like this:

# .aider.conf.yml
model: anthropic/claude-sonnet-4-6
weak-model: anthropic/claude-haiku-4-5
editor-model: anthropic/claude-sonnet-4-6
auto-commits: true
auto-lint: true
lint-cmd:
  - "python: ruff check --fix"
  - "javascript: eslint --fix"
  - "go: golangci-lint run --fix"
test-cmd: "pytest -x"
suggest-shell-commands: true
notifications: true
show-diffs: true
chat-history-file: .aider.chat.history.md
input-history-file: .aider.input.history

Top-level CLI flags reference

This table is the working reference for the most-used flags. Run aider --help for the full 520-line listing if you need an obscure switch.

Flag	Purpose
`--model MODEL`	Set the main chat model. Provider/name format, example: `anthropic/claude-sonnet-4-6`.
`--weak-model MODEL`	Cheap model for commit messages and summaries.
`--editor-model MODEL`	The model that applies edits during architect mode.
`--list-models QUERY`	Print every model whose name contains QUERY.
`--api-key PROVIDER=KEY`	Set a provider key inline.
`--set-env VAR=VAL`	Set arbitrary env vars before starting.
`--reasoning-effort LEVEL`	Reasoning effort knob for o-series and Sonnet 4.6+ thinking.
`--thinking-tokens N`	Cap on thinking tokens for thinking-capable models.
`--edit-format FMT`	Override the model’s default edit format (`diff`, `whole`, `udiff`, `diff-fenced`).
`--architect`	Switch on architect mode (planner + editor model).
`--auto-accept-architect`	Skip the confirmation prompt between architect plan and edit.
`--map-tokens N`	Repo map token budget. `0` disables.
`--map-refresh MODE`	`auto`, `always`, `files`, or `manual`.
`--cache-prompts`	Use prompt caching where the provider supports it.
`--cache-keepalive-pings N`	Keep the cache warm across N idle minutes.
`--max-chat-history-tokens N`	Compact older history above this threshold.
`--no-git`	Run without git (no auto-commits, no diff flow).
`--no-auto-commits`	Keep git but disable per-edit commits.
`--dirty-commits` / `--no-dirty-commits`	Commit pre-existing dirty changes when Aider runs.
`--commit`	Run, commit existing changes, exit.
`--commit-prompt PROMPT`	Override the system prompt used to write commit messages.
`--lint`	Lint and fix existing code, then exit.
`--lint-cmd CMD`	Per-language lint command. Pass multiple times.
`--auto-lint` / `--no-auto-lint`	Lint after every edit cycle.
`--test`	Run tests and let Aider iterate fixes.
`--test-cmd CMD`	Test command Aider uses for `--test` and `--auto-test`.
`--auto-test` / `--no-auto-test`	Run tests after every successful edit.
`--watch-files`	Re-read changed files automatically (no `/add`).
`--message MSG`	One-shot mode. Run MSG, exit.
`--message-file PATH`	Read the one-shot prompt from a file.
`--load PATH`	Replay a saved `/command` file on launch.
`--apply FILE`	Apply a diff file Aider produced earlier.
`--apply-clipboard-edits`	Apply edits pasted into the clipboard.
`--show-repo-map`	Print the repo map and exit.
`--show-prompts`	Print the assembled system prompts and exit.
`--browser` / `--gui`	Launch Aider’s browser UI instead of the TUI.
`--copy-paste`	Use clipboard ferry mode for offline / pay-per-message workflows.
`--vim`	Vim-style key bindings in the input.
`--multiline`	Multi-line input mode (Meta-Enter to submit).
`--yes-always`	Auto-confirm every prompt. Use carefully.
`-c, --config PATH`	Use an explicit config file.
`--env-file PATH`	Use an explicit .env file.
`--shell-completions SHELL`	Print bash, zsh, or tcsh completions.

Model selection and provider routing

Aider speaks every major LLM provider through LiteLLM. The model string is provider/model-name. Skip the provider for OpenAI:

# Anthropic
aider --model anthropic/claude-sonnet-4-6
aider --model anthropic/claude-opus-4-7

# OpenAI (no provider prefix)
aider --model gpt-5
aider --model o3

# Google
aider --model gemini/gemini-2.5-pro
aider --model gemini/gemini-2.5-flash

# DeepSeek
aider --model deepseek/deepseek-chat
aider --model deepseek/deepseek-reasoner

# AWS Bedrock (requires AWS_PROFILE)
aider --model bedrock/anthropic.claude-sonnet-4-6

# Local Ollama
aider --model ollama_chat/llama3.3:70b
aider --model ollama_chat/qwen2.5-coder:32b

# OpenRouter
aider --model openrouter/anthropic/claude-sonnet-4-6
aider --model openrouter/google/gemini-2.5-pro

The full list of known models is huge. Filter it from the CLI:

$ aider --list-models claude
Models which match "claude":
- anthropic/claude-haiku-4-5
- anthropic/claude-opus-4-7
- anthropic/claude-sonnet-4-6
- anthropic/claude-sonnet-4-5-20250929
...

Main, weak, and editor models

Aider runs three roles concurrently. Tune each for the right cost/quality tradeoff:

Main model: handles your prompts and code edits. Pick the smartest model your budget allows.
Weak model: writes commit messages, summarises history. Cheap is fine. claude-haiku-4-5, gpt-5-mini, gemini-2.5-flash are all good picks.
Editor model: in architect mode, applies the planner’s instructions to files. Pick a model strong at structured output.

Chat modes

Switch modes mid-session with the corresponding slash command. Each mode shapes Aider’s behaviour:

Mode	Slash	Behaviour
Code (default)	`/code`	Reads, edits, commits. The standard pair-programming loop.
Architect	`/architect`	Two-step: a planner model proposes changes, the editor model applies them. Best for larger refactors.
Ask	`/ask`	Read-only Q&A. No edits. Best for code review and exploration.
Help	`/help`	Aider answers questions about itself, including command and config questions.

Architect mode usually pairs well with thinking-capable models. A typical pairing:

aider --architect \
  --model anthropic/claude-opus-4-7 \
  --editor-model anthropic/claude-sonnet-4-6 \
  --auto-accept-architect

Slash commands inside Aider

Aider’s interactive interface has the richest command surface of any terminal AI agent. Memorise the ones marked with a star, the rest are reachable by typing / and tabbing.

Command	Purpose
`/add <files>` *	Add files to the chat (Aider can edit them).
`/drop [files]` *	Remove files from the chat. No args drops everything.
`/ls`	List files currently in the chat.
`/read-only <files>` *	Add files for reference but block edits to them.
`/clear`	Clear the visible chat history.
`/reset`	Drop all files and clear history.
`/tokens` *	Print token usage for the current chat. The cost watchdog.
`/cost`	Show the running session cost.
`/code` *	Switch to code mode.
`/architect` *	Switch to architect mode.
`/ask` *	Switch to ask mode (read-only).
`/chat-mode <name>`	Generic mode switcher.
`/model <name>` *	Switch the main model on the fly.
`/editor-model <name>`	Switch the editor model.
`/weak-model <name>`	Switch the weak model.
`/think-tokens N`	Set thinking-token budget per turn.
`/reasoning-effort LEVEL`	Set reasoning effort for compatible models.
`/diff` *	Show the diff Aider just wrote.
`/undo` *	Revert the last commit Aider made.
`/git <cmd>`	Run a git command without leaving the agent.
`/commit [msg]`	Commit dirty changes manually.
`/run <cmd>` *	Run a shell command and feed the output into the chat.
`/test [cmd]`	Run the configured test command. Aider sees the output.
`/lint`	Run the configured lint command.
`/web <url>`	Fetch a URL and add the rendered text to the chat.
`/voice`	Voice input (Whisper). Requires `portaudio`.
`/paste`	Paste image or text from the clipboard.
`/copy`	Copy the last assistant reply to the clipboard.
`/copy-context`	Copy the assembled system prompt for inspection.
`/load PATH`	Run a saved `/command` script.
`/save PATH`	Save the current session as a replayable script.
`/multiline` or `/ml`	Toggle multi-line input.
`/vim`	Toggle Vim key bindings.
`/editor [cmd]`	Open `$EDITOR` for a long prompt.
`/map`	Print the current repo map.
`/map-refresh`	Force a repo-map refresh now.
`/settings`	Print effective settings.
`/report`	Open a pre-filled GitHub issue with anonymised diagnostics.
`/help`	Aider answers questions about itself.
`/quit` or `/exit`	Exit cleanly.

Files, repo map, and context

Aider always sends three things to the model: the files in the chat (full contents), the repo map (skeleton of every other file), and the conversation history. Tune each lever based on repo size and budget.

/add and /drop discipline

Smaller chats run faster, cost less, and produce sharper edits. Add files when you need them, drop them when done:

/add src/auth/*.py
/add tests/auth/test_login.py

# After the change is in
/drop tests/auth/test_login.py

/read-only for reference docs

If a file is informative but should not be edited (a README, an upstream lib, a config schema), pass it through /read-only instead of /add:

/read-only docs/api-spec.md
/read-only ../external-lib/v3/types.d.ts

Repo map tuning

The repo map is Aider’s skeleton view of the codebase. Default budget is 1024 tokens, raise or lower with --map-tokens. On a tiny repo, set it to 0 and save tokens. On a sprawling monorepo, raise it to 4096 or 8192 so Aider has enough context to find symbols you didn’t /add:

aider --map-tokens 4096 --map-refresh auto
/map           # inspect what the model sees
/map-refresh   # rebuild after big file moves

Git integration

Aider commits after every successful edit by default. Each commit message is generated by the weak model and tagged with Aider as the committer. Three knobs control the behaviour:

# Disable auto-commits for the session
aider --no-auto-commits

# Commit existing dirty changes before Aider starts editing
aider --dirty-commits

# Stop trusting Aider with attribution
aider --no-attribute-author --no-attribute-committer

# Skip git entirely (no repo, no commits, no diffs)
aider --no-git

Undo and diff loops

The fastest workflow is: ask, review the diff, undo if wrong, retry with a tighter prompt:

> refactor src/auth/login.py to use bcrypt instead of argon2
... edits applied, commit abc123
/diff             # what changed
/undo             # back out the commit
> refactor src/auth/login.py to use bcrypt, but keep the existing rate-limiter intact

Linting and testing in the loop

Aider can run your linter and test suite after every edit and feed the output back into the chat. This is the “self-healing” loop: model edits, lint fails, model fixes, tests pass.

# Per-language lint commands
aider \
  --auto-lint \
  --lint-cmd "python: ruff check --fix" \
  --lint-cmd "javascript: eslint --fix" \
  --lint-cmd "go: golangci-lint run --fix"

# Test command Aider iterates against
aider \
  --auto-test \
  --test-cmd "pytest -x --tb=short"

Inside a session you can trigger the same flow on demand:

/lint
/test
/test pytest tests/test_auth.py -v

Voice and image input

Aider supports voice prompts via Whisper and image attachments for vision-capable models:

# Voice input
sudo apt install -y portaudio19-dev   # required dependency on Linux
aider --voice-language en
> /voice
> (speak your prompt)

# Paste a screenshot from the clipboard
aider --model anthropic/claude-sonnet-4-6
> /paste
> explain this error in the screenshot

Headless and CI mode

The --message and --message-file flags drive non-interactive runs. Combine with --yes-always for unattended pipelines:

# One-shot CI fix
aider \
  --message "fix every failing pytest in tests/" \
  --yes-always \
  --auto-test --test-cmd "pytest -x" \
  --no-show-release-notes

# Apply a precomputed prompt file
aider --message-file .ci/upgrade-django.txt --yes-always

# Apply a saved /command script (recreate a deterministic session)
aider --load .aider/commands/refactor-auth.txt

For pure batch use without interactivity, pair with --exit to leave immediately after the message processes.

Caching and history

Prompt caching is a major cost lever on Anthropic and OpenAI. Turn it on, then keep the cache warm during pauses:

aider --cache-prompts --cache-keepalive-pings 5

History files default to .aider.input.history and .aider.chat.history.md at the repo root. The chat history is human-readable Markdown, easy to grep:

grep -A4 "refactor login" .aider.chat.history.md
aider --restore-chat-history    # default true
aider --no-restore-chat-history # start blank

Aliases and aider.model.metadata.json

Long model names get tedious. Define aliases in the config file:

# .aider.conf.yml
alias:
  - "sonnet:anthropic/claude-sonnet-4-6"
  - "opus:anthropic/claude-opus-4-7"
  - "fast:anthropic/claude-haiku-4-5"
  - "g25:gemini/gemini-2.5-pro"
  - "local:ollama_chat/qwen2.5-coder:32b"

Then pick from the CLI:

aider --model sonnet
aider --model opus --weak-model fast --editor-model sonnet

For non-default models or self-hosted endpoints define metadata in .aider.model.metadata.json at the repo root or $HOME:

{
  "openai/local-llama": {
    "max_tokens": 8192,
    "max_input_tokens": 32000,
    "input_cost_per_token": 0,
    "output_cost_per_token": 0,
    "litellm_provider": "openai",
    "supports_function_calling": false
  }
}

Watch-files mode for IDE-style flow

--watch-files turns Aider into a passive sidecar. Edit any file in your editor, append a special comment like # aider: refactor this, and Aider picks it up automatically:

aider --watch-files

Useful when you live in VS Code or vim and want occasional AI assistance without context-switching to the terminal.

Browser UI

Aider ships a Streamlit-based browser UI for users who prefer chat-style interfaces:

aider --browser
# or
aider --gui

It listens on http://127.0.0.1:8501. Same model, same files, same slash commands, just rendered in a browser.

Common errors and fixes

Error: “OpenRouter authentication did not complete successfully”

Aider tried to open a browser-based OAuth flow on a headless box. Either set the provider key directly (OPENROUTER_API_KEY in .env) or pass --api-key openrouter=<key>.

Error: “Failed to build numpy==1.24.3”

This shows up when pipx install aider-chat picks a Python that the pinned NumPy refuses to compile against. The fix is the bootstrapper: install aider-install instead of aider-chat directly, and let it pick a compatible Python.

Error: “litellm.AuthenticationError”

Provider key is missing or wrong. Verify the key is exported, the env var name matches the provider (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY), and the .env file is in the repo root that Aider runs from.

Issue: portaudio missing on Linux

/voice requires the system PortAudio library. Install it with sudo apt install -y portaudio19-dev on Debian/Ubuntu and sudo dnf install -y portaudio-devel on Rocky/AlmaLinux/Fedora before launching Aider.

Aider vs Claude Code vs Codex CLI

Three terminal AI coding agents, three philosophies:

Aider: git-native, multi-provider, repo-map-aware, command-rich. Best when you want fine-grained control and provider flexibility.
Claude Code: deepest agent ecosystem, hooks, skills, plugins. See the Claude Code cheat sheet.
Codex CLI: tight focus, OpenAI-only, very strong at short surgical refactors. See the Codex CLI cheat sheet.
OpenCode: open-source TUI, also multi-provider. See the OpenCode setup guide.

Frequently asked questions

Where is the Aider config file?

Aider searches for .aider.conf.yml in the git repo root, then the current working directory, then $HOME. The first one found wins. Pass -c PATH to override entirely.

How do I disable auto-commits?

Pass --no-auto-commits on the command line, or set auto-commits: false in .aider.conf.yml. Aider will still track edits, you just commit yourself with /commit or external git.

What is architect mode in Aider?

Architect mode runs two models per turn. A planner model proposes the change in plain language, an editor model applies the change to files. Useful for larger refactors where structured output and reasoning come from different model strengths.

How do I use Aider with Ollama?

Run ollama serve, pull a coder-tuned model with ollama pull qwen2.5-coder:32b, then launch Aider with aider --model ollama_chat/qwen2.5-coder:32b. Pair with the Ollama commands cheat sheet for model management.

Can Aider run in CI?

Yes. Use --message for a one-shot prompt, --yes-always to auto-confirm, --auto-test --test-cmd "pytest" for self-healing test runs, and --no-show-release-notes to keep logs clean.

Keep this open while you work

Aider’s surface keeps growing release after release. When a new version ships check the freshness block at the top of this page, then re-read the section that changed. Pair this with the Aider setup guide for first-time install, and with the Claude Code cheat sheet if you alternate between the two agents.