OpenHands CLI Cheatsheet - Autonomous Coding Agent
Pairing assistants ask you to approve every step; OpenHands is aiming at something else. It takes a task, plans and executes on its own, and hands back a finished feature. This table groups startup and tasks, resume and headless runs, run modes, MCP management, configuration and installation, and interactive shortcuts, concentrating on where autonomous agents actually fail in practice: how to continue after a crash, how to stop a headless run from looping forever, and how loose the approval mode should be. The deciding question is verifiability. If success can be judged by a test result or an exit code, headless batch execution is safe; if you need to inspect intermediate state, stay interactive. Reach for it when running bulk refactors or fixes in CI, when a repository needs a set of boilerplate features, or when driving benchmark loops. What distinguishes it from other agents is that sandboxing and approval policy are configured by default in ~/.openhands/config.toml, so model and sandbox choices change in one place instead of on every command line.
Typical Use Case
For developers who want an autonomous agent operating on a real repository — writing code, adding tests, working through issues. What separates OpenHands from a conversational assistant is that it genuinely executes commands and reads and writes files, which makes run modes and permission control more important than prompt tricks. This sheet separates six groups: startup and task, resume and headless, run modes, MCP management, configuration, and interaction keys. Note that --always-approve and --headless decide whether the agent acts on its own.
Launch & Task 5
openhandsopenhands -t "Implement user auth"openhands -f task.txtopenhands --always-approveopenhands --llm-approveResume & Headless 5
openhands --resumeopenhands --resume --lastopenhands --resume <id>openhands --headless -t "task"openhands --headless --jsonRun Modes (Web/ACP/Cloud) 5
openhands webopenhands serveopenhands acpopenhands loginopenhands cloud -t "task"MCP Management 5
openhands mcp listopenhands mcp add tavilyopenhands mcp enable <name>openhands mcp disable <name>openhands --from-issue <url>Config & Install 5
uv tool install openhands --python 3.12pip install openhands-ai==0.45.0docker pull openhands/runtime:0.45-cpuopenhands --override-with-envscat ~/.openhands/config.tomlHotkeys 5
Ctrl+PEscCtrl+Q/exitopenhands --max-iterations 50Parameter matrix
| Parameter | Effect | Example |
|---|---|---|
-t "<task>" | Run straight away with the task supplied inline. | openhands -t "implement user authentication" |
-f task.txt | Read the task description from a file. | openhands -f task.txt |
--headless | Run without the interactive interface. | openhands --headless -t "<task>" |
--headless --json | Headless plus JSON output, which is easy for scripts to parse. | openhands --headless --json -t "<task>" |
--always-approve | Auto-approve every action (synonym of yolo). | openhands --always-approve -t "<task>" |
--llm-approve | Auto-approve only the actions initiated by the LLM. | openhands --llm-approve |
--resume --last | Resume the most recent session. | openhands --resume --last |
--max-iterations | Cap the number of iterations so the agent cannot run away. | openhands --max-iterations 50 |
mcp add / enable | Add and then enable an MCP server. | openhands mcp add tavily |
web / serve | Start the Web UI, or run as a resident service. | openhands web |
--override-with-envs | Let environment variables override the config file. | openhands --override-with-envs |
Ctrl+P / Esc | Open the command palette, or abort the current task. | Press Esc in the interactive session to abort |
Common pitfalls
SymptomThe agent edited files it should not have, or ran destructive commands.
CauseApproval was disabled with --always-approve (yolo), so every action skipped confirmation.
FixKeep human confirmation on by default; when automation is genuinely required, use --headless in a restricted environment and set a --max-iterations ceiling first.
SymptomThe task loops over the same action until it exhausts its budget.
CauseNo iteration ceiling was set, so the agent kept retrying along a failing path.
FixAdd a ceiling such as --max-iterations 50 so the run stops on its own.
SymptomAfter an interruption the task context is gone and everything restarts from scratch.
CauseSession resume was never used.
FixRecover the latest session with openhands --resume --last, or name a specific one with --resume <id>.
SymptomIn CI the invocation just waits for input, or fails outright.
CauseIt dropped into the interactive mode instead of running headless.
FixUse --headless and add --json so the output can be parsed by the script.
SymptomThe agent cannot reach external information and stalls on a step that needs research.
CauseThe matching MCP server was never mounted.
FixAdd it with openhands mcp add tavily, then activate it with mcp enable <name>.
SymptomEdited source never shows up in the container and disappears after a restart.
CauseThe runtime is an isolated sandbox and the host directory was not mounted correctly.
FixVerify the working directory mount configuration, or run in non-sandbox mode directly against the local repository.
Troubleshooting
1Run it headless once to confirm the behaviour
openhands --headless --json -t "add tests for the auth module"JSON output is easy for a script to consume, and it avoids accidentally triggering the interactive prompt.
2Set an iteration ceiling to prevent runaway runs
openhands --max-iterations 50Any looping task needs a ceiling, otherwise it can keep consuming resources indefinitely.
3Resume an interrupted session
openhands --resume --lastResume a specific session by ID with openhands --resume <id>.
4Inspect the configuration and model settings
cat ~/.openhands/config.tomlThe file has core, llm, sandbox and planner sections; changes there can be overridden from the environment with --override-with-envs.
5List the MCP servers that are mounted
openhands mcp listConfirm that the tools you need are present and enabled.
Command Examples
Pick up an abandoned run: resume the most recent session
openhands --resume --lastThis is the shortcut for the task you kicked off a moment ago and never finished. Because --last always picks the newest session, it is easy to land in the wrong one when several runs overlap; in that case follow --resume with an explicit session ID.
Keep the task in a file so the shell cannot mangle a long prompt
openhands -f task.txtEquivalent in effect to openhands -t "implement user auth", except the description no longer passes through shell parsing. Prefer the file form whenever the task text contains newlines, backticks, or other shell metacharacters.
Headless plus JSON: structured results inside CI
openhands --headless -t "task" --json--json makes the result machine-parseable, so the pipeline no longer depends on log scraping. Add --max-iterations 50 on top to cap the agent loop and keep a runaway iteration from stalling the build.
Wire up an MCP server: add, enable, verify, then park it
openhands mcp list
openhands mcp add tavily
openhands mcp enable tavily
openhands mcp disable tavilyadd only registers the server while enable is what mounts it into a session. Use list to confirm the current state, and disable to take one server out of local runs temporarily without deleting and reinstalling it later.
Common Pitfalls
- --always-approve is the same thing as --yolo: nothing inside the sandbox asks for confirmation, so one bad judgement call turns into edited files, installed dependencies, or a destructive command. Use it only in a clean workspace you can rebuild.
- --from-issue <url> turns third-party issue text into your task description, which means external prose is steering changes on your machine. Verify the link is trustworthy and start from a branch before running it against anything important.
- Without --max-iterations, a multi-step task can spin for a long time unattended and keep burning API quota. Always state an explicit ceiling for headless and CI runs.
- pip install openhands-ai==0.45.0 pins the CLI, and docker pull openhands/runtime:0.45-cpu must line up with that pin. A mismatched CLI and runtime pair shows up as sandbox startup failures that are painful to diagnose.
- What lives in ~/.openhands/config.toml decides LLM, sandbox, and approval behaviour. When you launch with --override-with-envs the environment wins over same-named file keys, and that shadowing layer is the usual reason a config edit appears to do nothing.
Tips
- OpenHands aims to "write a whole repo" autonomously — more aggressive than pair programming; for big tasks use
--resumeto keep checkpoints so a crash can continue. - For headless batch use
--headless --jsonin pipelines, with--max-iterationsto stop runaway loops. - Don't bare-run
--always-approveon sensitive/prod tasks; at least use--llm-approveor validate small with--headlessfirst. - Config lives in
~/.openhands/config.toml(llm/sandbox/planner) — set model and sandbox policy once, no per-run flags.
FAQ
How do I continue a task I abandoned hours ago instead of starting a fresh run?
Bring the session back with openhands --resume, which restores the workspace state and the conversation context together. Add --last to skip the picker and jump into the most recent session, or follow --resume with a specific session ID when you already know which one you want. Prefer the explicit ID over --last so you do not land in an unrelated older session.
What is the real difference between --always-approve and --llm-approve?
--always-approve (same as --yolo) lifts every confirmation prompt, including the ones the agent decides on its own. --llm-approve only clears actions the LLM initiates, a narrower grant that keeps a human gate in the loop. For day-to-day interactive work --always-approve is the least friction. On a shared machine, or when the task came from outside such as an issue pulled in with --from-issue, keeping manual approval is the safer call.
How do I make headless runs consumable from CI or a script?
The key is --json. Run a single task with openhands --headless, and adding --json turns the output into parseable structured results so your script never has to scrape human-readable logs. Pair it with openhands --headless -t "task" to hand over the task description inline, and add a ceiling such as --max-iterations 50 so an agent run cannot sprawl inside your pipeline.
I added an MCP server but the agent ignores it. What am I missing?
Registration and activation are two separate steps. openhands mcp add tavily only records the server; it stays inactive until you run openhands mcp enable tavily, and only then is it attached to your sessions. Use openhands mcp list to check what is registered and which entries are currently enabled. If you only need to park one temporarily, openhands mcp disable takes it out of the run without deleting it.
My config.toml edit seems to be ignored. What is the override order?
User-level configuration lives in ~/.openhands/config.toml, split into core, llm, sandbox, and planner sections. By default that file is the final word. The moment you pass --override-with-envs, environment variables take precedence over the same keys in the file. Debug in that order: first cat ~/.openhands/config.toml to confirm what the file actually says, then check whether the launch command carries --override-with-envs. Reversing those two steps is what produces the feeling that the file edit did nothing.
Official References
Each command links to its official documentation below, so you can verify the latest usage and read deeper.
Maintained by LaoHand
Publicly updated on Aug 21, 2026, continuously proofread against official docs.
Contact Us
Wrong command or description? Send us corrections, business inquiries or product feedback by email.
Contact Us