Command line and tools
Run a whole request from a terminal or a script with the same agent team, safety rules and checks as the app. Options, exit codes, examples and what is logged.
Last updated
maxtkn run does a request without the desktop app: you give it a project folder and a sentence, and it runs the team, prints what happened and exits with a code that says how it went. It is made for scripts, CI jobs and runs started by your computer’s scheduler.
maxtkn run [options] "<what to do>"
maxtkn run [options] - # read the request from standard input
maxtkn run [options] -- "<text>" # -- ends the options; the text may start with a dashmaxtkn run --verify "add a dark mode switch to the settings page"The command line never reads the desktop app’s stored keys. It reads them from environment variables only: ANTHROPIC_API_KEY for a claude-… model, and OPENAI_API_KEY or OPENROUTER_API_KEY for others. A model named like vendor/model goes to OpenRouter; any other goes to OpenAI unless you pass --base-url. To use a different variable, pass its name with --api-key-env. Never put the key itself on the command line. A server on your own computer (Ollama, LM Studio) needs no key, and neither does a model that uses a signed-in Claude Code or Codex plan.
$env:ANTHROPIC_API_KEY = "<your key>"
maxtkn run --team solo "fix the failing test"| Option | Meaning |
|---|---|
-p, --project DIR | The project folder. Default: the current folder. |
--team ID | squad (default), solo, or another built-in team id. |
--model ID | claude-sonnet-5-5 by default, or any model your endpoint serves. |
--access MODE | ask, auto-edit (default) or full. |
--profile NAME | read-only, workspace, workspace-network (default) or full. |
--effort LEVEL | low, medium, high, xhigh or max. |
--base-url URL | An OpenAI-compatible endpoint, for example a local model server. |
--api-key-env NAME | The environment variable that holds the key. |
--yes-to TOOL | Allow one tool to run without asking, for example run_command. Repeat for more. |
--verify | Run the project’s own checks afterwards. A failure makes the exit code 1. |
--check | Run the acceptance checks in .maxtkn/acceptance.json afterwards. A check that fails or cannot run makes the exit code 1. |
--goal TEXT | Keep working until this is true. Each round is a run, then the criteria are checked for real. |
--goal-check CMD | A shell command that must exit 0 for the goal to be met. Repeat for more. Needs --goal. |
--max-rounds N | Most runs a goal may start. Default 8. |
--max-usd N | Money limit of a goal. A priced model gets a default. |
--worktree[=BASE] | Work in an isolated copy started from BASE (default: the current branch). Prints the branch and folder. Nothing is applied to your project. Needs git, a repository and a first commit. |
--trust | Let the project’s hooks, MCP servers and skill scripts run. Without it they are listed as skipped. |
--timeout SECS | Cancel after this long. Default 1800. |
--no-knowledge | Do not search the project’s documents and .maxtkn/memory. |
--json | Print one event per line as JSON. |
-h, --help / -v, --version | Show help or the version. |
| Code | Meaning |
|---|---|
| 0 | Done. With --goal: the goal is met. |
| 1 | An error or a failed check. |
| 2 | Usage: an unknown option or a missing value. |
| 3 | An approval was needed and denied. |
| 4 | Cancelled or timed out. |
| 5 | A goal ran out of rounds, time or money. |
There is nobody to approve anything, so anything that would ask is denied and listed at the end, unless --access full or --yes-to allows it. Plan mode is never used and questions resolve as skipped. A goal never allows Full access or --yes-to, and the time limit always applies. See the rule for unattended runs.
maxtkn run --team solo "a task tracker where I can add tasks"maxtkn run --goal "the tests pass" --goal-check "npm test" --max-rounds 4maxtkn run --worktree "add a contact form"Get-Content request.txt | maxtkn run -maxtkn run --base-url http://localhost:11434/v1 --model qwen2.5-coder "explain this project"Every run writes its events inside the project, in .maxtkn/runs/: a log with one redacted event per line, a human-readable walkthrough, any documents the team produced, and latest.json with the newest run’s outcome. Text that looks like a key is removed before it is written.
Something missing or wrong? Maxtkn is early-access software and these pages change with it. The changelog lists what changed in each build.