> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentuse.io/llms.txt > Use this file to discover all available pages before exploring further. # CLI Commands > Complete reference for all AgentUse CLI commands ## agentuse run Execute an agent file. ### Syntax ```bash theme={"system"} agentuse run [prompt...] [options] ``` ### Arguments Path to agent file (.agentuse or .md extension) or HTTPS URL Optional additional prompt to append to the agent's instructions ### Options ```bash theme={"system"} -q, --quiet Suppress info messages (only show warnings/errors) -d, --debug Enable verbose debug logging --no-code-mode Disable the default code_exec tool for controlled comparison and debugging --no-tty Disable TUI output (plain logs for piping/automation) -v, --verbose Show detailed execution information --timeout Maximum execution time in seconds (default: 300) -C, --directory Run as if agentuse was started in instead of the current directory --env-file Path to custom .env file -m, --model Override the model specified in the agent file --mock Mock all tool outputs with the LLM instead of executing them (no real side effects). Requires --mock-model. --mock-model Model that generates mock tool outputs (required with --mock; pick a cheap, reachable model) --mock-approval [d] Resolve the await_human gate deterministically instead of suspending: approve (default), reject, or comment: ``` The `--quiet` and `--debug` options cannot be used together. You can also set `NO_TTY=true` to force plain logging without spinners. ### Directory and Path Resolution #### Directory Override (-C, --directory) The `-C` or `--directory` option is the starting directory for the command: ```bash theme={"system"} # Without -C: runs from current directory agentuse run agent.agentuse # With -C: starts from the specified directory agentuse run agent.agentuse -C /path/to/project-or-subdir ``` #### Project Root Detection AgentUse searches from the current directory upward for `.agentuse/`, `.git/`, or `package.json`. If none are found, the starting directory is the project root. The project root is used for: * Loading `.env` files * Finding plugins in `.agentuse/plugins/` * Owning shared stores in `.agentuse/store/` * Grouping session state For `agentuse serve`, `-C` also defines the served scope: only `.agentuse` files under that directory are exposed, while state still belongs to the detected project root. This is useful for: * Running agents from different projects * CI/CD environments with complex directory structures * Testing with different configurations #### Path Resolution Rules Subagent paths and MCP server commands are resolved relative to the **agent file's directory**. See [Agent Syntax - Subagents](/reference/agent-syntax#subagents) for complete path resolution examples. ### Model Override The `--model` option allows you to override the model specified in an agent file at runtime. This is useful for: * **Testing**: Compare agent behavior across different models * **Cost Optimization**: Use cheaper models for development/testing * **Environment-Specific Models**: Different models for dev/staging/production * **Quick Experiments**: Try new models without editing files #### Format ``` provider:model[:env] ``` Where: * `provider`: A built-in provider (`anthropic`, `openai`, `openrouter`, `opencode-go`, `bedrock`) or a custom provider name * `model`: The specific model name (e.g., `claude-sonnet-4-6`, `gpt-5.5`, `glm-5-flash:q4_K_M`), or a [version alias](/reference/models#version-aliases) such as `claude-sonnet` * `env`: Optional environment suffix for API keys (e.g., `dev`, `prod`, or full env var name), built-in providers only A configured `@name` alias also works: `--model @fast`. #### Examples ```bash theme={"system"} # Override with OpenAI GPT-5 agentuse run agent.agentuse --model openai:gpt-5.6 agentuse run agent.agentuse --model opencode-go:kimi-k2.7-code # Use Anthropic Claude Haiku for quick testing agentuse run agent.agentuse -m anthropic:claude-haiku-4-5 # Track the newest model in a line, or use a configured alias agentuse run agent.agentuse -m anthropic:claude-sonnet agentuse run agent.agentuse -m @fast # Use different API key via environment suffix agentuse run agent.agentuse --model openai:gpt-5.6:dev agentuse run agent.agentuse --model opencode-go:kimi-k2.7-code:dev # This will use OPENAI_API_KEY_DEV instead of OPENAI_API_KEY # Use specific environment variable agentuse run agent.agentuse --model anthropic:claude-sonnet-5:ANTHROPIC_API_KEY_PERSONAL ``` When overriding models, provider-specific options (like OpenAI's `reasoningEffort`) will be ignored if you switch to a different provider. An explicit model override propagates to every nested sub-agent. Without `--model`, each agent uses the model declared in its own file; a parent's configured model is not inherited. Alias fallback candidates and cooldowns propagate as one resolved policy and remain stable across session resume. ## agentuse test Choose what you want to check: | Command | Description | | - | - | | `agentuse test workflow [prompt...]` | Check the agent's steps and approval branches using simulated tool responses. | | `agentuse test result --session ` | Generate from a past job's evidence and compare the new result with the original. | ### Workflow options ```text theme={"system"} --scope all|gated Default: all. Gated simulates only gated bash; other tools run live. --approval approve (default), reject, or comment: --mock-model Model fabricating responses; or set AGENTUSE_MOCK_MODEL --no-code-mode Disable code_exec for comparison ``` ### Result options ```text theme={"system"} --session Required real source session; finished or awaiting approval --selector-model Evidence selector on first use; defaults to the agent model --judge Optional local agent defining quality criteria, run without tools ``` Result tests reuse the first validated evidence selection for the source session. They load current instructions and explicit read-only reference files. They do not execute workflow tools or expose the old draft to the writer or judge. Without a judge, `generated` means comparison available, not quality passed. With a judge, `passed` means the new result meets its criteria, not proof of improvement. `failed`, `incomplete`, and `error` return exit code 1; `generated` and `passed` return 0. Reports include the evidence path and reference hashes. Both modes accept `--quiet`, `--debug`, `--no-tty`, `--compact`, `--timeout`, `-C`, `--env-file`, `--model`, and `--json`. Put options after the mode. ```bash theme={"system"} agentuse test workflow reply.agentuse --approval reject agentuse test result reply.agentuse --session agentuse test result reply.agentuse --session --judge quality.agentuse --json ``` Compatibility: `test [prompt...]` retains adaptive mocking, and `test --replay ` retains strict recorded-call replay. Use `./workflow` or `./result` to refer to files whose names collide with the new subcommands. See [Testing agents](/guides/testing-agents) for evidence selection, isolation, limitations, approval simulation, and the complete workflow. ### Full mock (`--scope all`, or `run --mock`) Full-scope mock answers **every** tool call with an LLM-generated result instead of executing it. The agent runs for real; only tool execution is faked. The same mode is available as low-level plumbing on `run`: ```bash theme={"system"} agentuse run agent.agentuse --mock --mock-model anthropic:claude-haiku-4-5 ``` **Use the lowest-end model you can reach for `--mock-model`.** Mocking is not a reasoning task: the model only has to fabricate a plausible result for a tool given its name and arguments. Your agent's *actual* reasoning still runs on its own model, untouched. A small, fast model produces fine mock output while keeping cost and rate-limit pressure low, which matters because mock fires one LLM call for **every** tool result (and they run concurrently when the agent batches tool calls). Good low-end picks, by provider: | Provider | Suggested `--mock-model` | | - | - | | `anthropic` | `anthropic:claude-haiku-4-5` | | `openai` | `openai:gpt-5.4-nano` | | `openrouter` | `openrouter:deepseek/deepseek-v4-flash` | Pick one in a provider you're authenticated for. (Model IDs drift over time; the current low-end tier is the rule, not these exact names.) * **A mock model is required.** Mock fires an LLM call for *every* tool result, so it must run on a model you can reach. It is deliberately **not** defaulted to the agent's own model: that ran mock onto the agent's premium, rate-limited token and produced opaque `429`s. Provide it per run with `--mock-model`, or set a global default once via `AGENTUSE_MOCK_MODEL` in the shell, `~/.agentuse/.env`, or the [`env` block of `~/.agentuse/config.json`](/reference/configuration-files#global-env-defaults). The flag wins over all of them. * **Sub-agents run for real**; their leaf tools are mocked. * **The approval gate stays real under `run --mock`**: `await_human` still suspends so you can verify the agent pauses for approval. Pass `--mock-approval` for fully-unattended runs (`agentuse test` defaults to this): the gate resolves **deterministically** (no LLM plays the reviewer) instead of suspending. * `--mock-approval` (or `--mock-approval approve`) auto-approves. The approval grants the [gated-command lease](/guides/approval-gates) derived from the gate's `changes[]` exactly like a real reviewer approval, so `tools.bash.gated` flows complete end-to-end. On a pick gate the recommended option is chosen (else the first), returned as `choice`. * `--mock-approval reject` forces the reject branch: the gate seals (terminal for the run) so you can test the agent's cleanup path. * `--mock-approval comment:` forces the revise-and-re-gate branch with `` as the reviewer comment. The comment applies to the **first** gate only; the re-gate that follows is approved, so the run exercises the revision path and still finishes. (Repeating the comment on every gate would loop an obedient agent until it gave up.) MCP servers still connect at startup for tool discovery, but no tool executes (no mutations). Mock outputs are non-deterministic; mocked approval decisions are deterministic. ### Remote Agent Security When running agents from remote URLs: 1. **HTTPS Only**: Only HTTPS URLs are allowed for security 2. **File Extension**: Remote agents must have `.agentuse` extension 3. **Interactive Confirmation**: AgentUse will show a security warning with options: * `[p]review` - Fetch and display the agent content before running * `[y]es` - Execute the agent directly * `[N]o` - Abort execution (default) Example security prompt: ``` ⚠️ WARNING: You are about to execute an agent from: https://example.com/agent.agentuse Only continue if you trust the source and have audited the agent. [p]review / [y]es / [N]o: ``` ### Examples ```bash theme={"system"} # Run agent from current directory agentuse run hello.agentuse # Run agent from subdirectory cd agents/subfolder agentuse run my-agent.agentuse # Finds .env and plugins at project root # Change to different directory first with -C agentuse run agent.agentuse -C /my/project # Same as: cd /my/project && agentuse run agent.agentuse # Run agent from a different project agentuse run newsletter/writer.agentuse -C ~/projects/content # Use custom environment file agentuse run agent.agentuse --env-file .env.production # Run with additional prompt agentuse run assistant.agentuse "Help me write an email" # Run with multi-word prompt agentuse run code-review.agentuse "focus on security and performance issues" # Run remote agent (requires HTTPS and .agentuse extension) # Shows security warning and requires confirmation agentuse run https://example.com/agent.agentuse # Run remote agent with additional prompt agentuse run https://example.com/agent.agentuse "use production settings" # Run with debug output agentuse run agent.agentuse --debug # Run with additional prompt and verbose output agentuse run agent.agentuse "be thorough" --verbose # Run with custom timeout agentuse run agent.agentuse --timeout 600 # Run quietly (only warnings/errors) agentuse run agent.agentuse --quiet # Disable TUI output for piping/automation agentuse run agent.agentuse --no-tty # Override model at runtime agentuse run agent.agentuse --model openai:gpt-5.4-mini # Override model and add prompt agentuse run agent.agentuse "be concise" --model anthropic:claude-haiku-4-5 # Use development API key with model override agentuse run agent.agentuse -m openai:gpt-5.6:dev # Override model for agent with sub-agents (all will use the same model) agentuse run orchestrator.agentuse --model openai:gpt-5.4-mini ``` ### Replay a recorded session ```bash theme={"system"} agentuse test --replay [--json] [--model ] ``` Generate with current instructions and recorded tool results. Stops at the first proposal before automated review, final output, or an unmatched call. Never executes live tool operations or fabricates missing results. See [Replay recorded inputs](/guides/replay) for matching and reference-file behavior. ## agentuse sessions View and resume AgentUse sessions. ### Syntax ```bash theme={"system"} agentuse sessions list [options] agentuse sessions show [options] agentuse sessions resume [options] agentuse sessions reconcile [options] agentuse sessions backfill-blockers [options] agentuse sessions path [options] ``` `agentuse sessions` is a shortcut for `agentuse sessions list`. Session data is stored globally and partitioned by project. CLI session commands default to the current project; use `--all` or `--all-search` when you are not sure which project owns a session. ### List Sessions ```bash theme={"system"} agentuse sessions list agentuse sessions list --all agentuse sessions list --project ../other-project ``` List options: ```bash theme={"system"} -s, --subagents Include subagent sessions -n, --limit Limit number of sessions to show -j, --json Output as JSON --no-mock Hide mock/test runs (listed by default, marked "· mock") --all Show sessions across all projects --project [path] Show sessions for a project path; defaults to current project ``` ### Show a Session ```bash theme={"system"} agentuse sessions show 01K... agentuse sessions show 01K... --all-search agentuse sessions show 01K... --project ../other-project ``` Show options: ```bash theme={"system"} -j, --json Output as JSON -f, --full Show full tool input/output --project [path] Search a project path; defaults to current project --all-search Search all projects if not found in the selected project ``` ### Resume a Session Use `agentuse sessions resume` for local continuation. It supports suspended approval sessions and ended sessions. For a suspended approval session: ```bash theme={"system"} agentuse sessions resume 01K... --approve agentuse sessions resume 01K... --approve "Looks good" agentuse sessions resume 01K... --approve --choice candidate-2 agentuse sessions resume 01K... --reject "Not ready" agentuse sessions resume 01K... --comment "Please revise the CTA" agentuse sessions resume 01K... --comment "Keep intros factual, not salesy" --remember agentuse sessions resume 01K... --comment "Please revise with citations" --remember "Always include source links before publishing." ``` The CLI uses local session access as the trust boundary, so approval resumes do not require a resume token. The decision rules are the same as on the approval page: a pick gate (one with `options`) needs `--choice ` naming the option to approve, `--choice` only goes with `--approve`, and a draft that strict automated review sent back for revision guidance can be commented on or rejected but not approved. `--remember` saves the comment as a future instruction, and requires `--comment` (a non-empty one). Bare `--remember` reuses the comment text; passing a value (`--remember "..."`) overrides it. Passing `--remember` is itself the opt-in, so saving needs no `learning` config on the agent. The comment is still the feedback for this revision; the instruction is distilled from it, stored as `src:manual`, and injected into future runs once the agent has `learning.apply` enabled. It is also vetted against the agent's own instructions: a note that contradicts them is still saved, but quarantined with the conflict named rather than injected. For a suspended non-approval `await_*` tool (approval gates refuse `--tool-result`; use the decision flags above): ```bash theme={"system"} agentuse sessions resume 01K... --tool-result '{"status":"done"}' ``` For a completed or errored session, AgentUse starts a new run from the original agent file with continuation context: ```bash theme={"system"} agentuse sessions resume 01K... --prompt "Continue from here and add tests" ``` Resume options: ```bash theme={"system"} -C, --directory Run as if agentuse was started in --project [path] Search a project path; defaults to current project --all-search Search all projects if not found in the selected project -d, --debug Enable debug logging for resume ``` ### Reconcile Stuck Sessions Settle sessions still marked `running` whose owning process is gone. This is the same owner-liveness check `agentuse serve` performs at startup, but it sweeps as far back as you ask instead of the daemon's 30-day window. ```bash theme={"system"} agentuse sessions reconcile [options] ``` Reconcile options: ```bash theme={"system"} --lookback How far back to scan: a day count, or "all" (default: all) --dry-run Report what would be settled without writing -j, --json Output as JSON --all Reconcile across all projects --project [path] Reconcile a project path; defaults to current project ``` A run that is still executing anywhere is never touched: a live worker, a worker released across a daemon restart, or a plain terminal `agentuse run` all keep their session as-is, because the session records its owning process and reconcile checks that the process is actually alive. A 10-minute recency window backs that up, so a session written to very recently is left alone even if it comes from a build that predates owner tracking. Sessions suspended on a subagent that died are settled the same way, so a manager waiting on a child that will never report back stops sitting in limbo. Why this exists: runs orphaned before serve's 30-day startup window stayed `running` forever, inflating the dashboard's needs-attention counts with work that ended long ago. ```bash theme={"system"} # See what is stuck without changing anything agentuse sessions reconcile --dry-run # Settle everything in this project, however old agentuse sessions reconcile # Sweep the last week across every project, as JSON agentuse sessions reconcile --all --lookback 7 --json ``` ### Backfill Blockers Give older `INCOMPLETE` runs a blocker so they group with new ones, and dismiss failures too old to act on. It only adds fields: status and messages are never rewritten. ```bash theme={"system"} agentuse sessions backfill-blockers [options] ``` Backfill options: ```bash theme={"system"} --days Backfill failures last touched within this many days; dismiss older ones (default: 14) --dry-run Report what would change without writing -j, --json Output as JSON --all Sweep every project --project [path] Sweep a project path; defaults to current project ``` ### Show Storage Path ```bash theme={"system"} agentuse sessions path agentuse sessions path --project ../other-project ``` ## agentuse serve Start the AgentUse HTTP daemon to run agents via API. This enables integration with external applications, webhooks, approvals, Slack notifications, or any system that can make HTTP requests. ### Syntax ```bash theme={"system"} agentuse serve [options] ``` ### Options ```bash theme={"system"} -p, --port Port to listen on (default: 12233) -H, --host Host to bind to (default: 127.0.0.1) -C, --directory Directory to serve agents from; project state is detected upward --default Default project for POST /api/run when `project` is omitted -d, --debug Enable debug mode --no-code-mode Disable the default code_exec tool for every run launched by this daemon --public-url Externally reachable base URL used in approval links (or config serve.publicUrl) --no-auth Disable API key requirement for exposed hosts (dangerous) --no-log-file Disable writing serve logs to a file --open Open the Web UI in the default browser after startup --hide-agent-source Hide raw agent source in the dashboard and /api/agents/detail ``` ### Serving Multiple Projects AgentUse runs one serve daemon at a time. Repeat `-C` on that daemon to serve multiple scopes/projects: ```bash theme={"system"} agentuse serve -C ./projA -C ./projB ``` Project ids default to the `-C` directory basename. Duplicate ids fail startup. Each scope detects its project root independently, and each project loads its own `.env` / `.env.local` in its worker process. Use the request `project` field to choose a project. In multi-project mode, omitting it returns `400 PROJECT_REQUIRED` unless `--default ` is set. Starting a second daemon fails with the PID, address, projects, and log path of the daemon that is already running. This keeps approval links, Slack replies, session resumes, and API traffic routed through one owner. ### Global Config You can put serve defaults in `~/.agentuse/config.json`. See [Configuration Files](/reference/configuration-files#global-serve-config) for the schema and CLI override behavior. ### Authentication When binding to exposed hosts (not `127.0.0.1` or `localhost`), API key authentication is required: ```bash theme={"system"} # Set API key for authentication export AGENTUSE_API_KEY="your-secret-key" # Start server on all interfaces agentuse serve --host 0.0.0.0 ``` Clients must include the key in requests: ```bash theme={"system"} curl -X POST http://server:12233/api/run \ -H "Authorization: Bearer your-secret-key" \ -H "Content-Type: application/json" \ -d '{"agent": "my-agent.agentuse"}' ``` Use `--no-auth` to bypass authentication (dangerous for production). ### API Endpoints All JSON endpoints are served under the `/api/*` prefix; the un-prefixed root paths (`/`, `/agents`, `/sessions`, `/schedules`, `/stores`, `/approvals`) serve HTML dashboard pages. `GET /` is the dashboard home: it links to those pages and lists the served projects with their agent and schedule counts. The per-session page `/sessions/:id` and its action subroutes (`/decision`, `/continue`, `/status`) carry their own capability auth (session token / API key / local). `POST /run`, `POST /resume/:id`, and the `POST /approvals/:id/...` action endpoints remain reachable at their original paths for backward compatibility, and `GET /approvals/:id` redirects to `/sessions/:id` (prefer the `/api/*` and `/sessions` paths; the legacy aliases will be removed later). #### GET /api Returns version, default project, and served projects. (`GET /` serves the HTML dashboard built from the same data.) ```json theme={"system"} { "version": "0.12.0", "update": { "currentVersion": "0.12.0", "latestVersion": "0.18.0", "packageManager": "npm", "command": "npm install -g agentuse@latest" }, "default": "projA", "projects": [ { "id": "projA", "path": "/abs/path/to/projA", "agentCount": 3, "scheduleCount": 1 }, { "id": "projB", "path": "/abs/path/to/projB", "agentCount": 2, "scheduleCount": 0 } ] } ``` `update` is present only when the cached npm registry result contains a newer AgentUse version from npm's `latest` dist-tag. The dashboard uses it for its dismissible update banner. `default` is `null` in multi-project mode without `--default`; single-project mode returns the sole project id. #### POST /api/run Execute an agent and receive the result. (Legacy alias: `POST /run`.) **Request Body:** ```json theme={"system"} { "agent": "path/to/agent.agentuse", "project": "projA", "prompt": "Optional additional prompt", "model": "anthropic:claude-sonnet-5", "timeout": 300, "maxSteps": 100 } ``` | Field | Type | Required | Description | | - | - | - | - | | `agent` | string | Yes | Path to agent file (relative to that project's root) | | `project` | string | Conditional | Required in multi-project mode unless `--default` is set | | `prompt` | string | No | Additional prompt to append to agent instructions | | `model` | string | No | Override the model specified in agent file | | `timeout` | number | No | Maximum execution time in seconds (default: 300) | | `maxSteps` | number | No | Maximum number of tool call steps | **Response (JSON):** ```json theme={"system"} { "success": true, "result": { "text": "Agent response text", "finishReason": "end-turn", "duration": 1234, "tokens": { "input": 500, "output": 200 }, "toolCalls": 3 } } ``` **Error Response:** ```json theme={"system"} { "success": false, "error": { "code": "AGENT_NOT_FOUND", "message": "Agent file not found: my-agent.agentuse" } } ``` #### GET /api/agents Lists the agents loaded by the daemon as JSON. `path` is relative to the project root, exactly as accepted by `POST /api/run`. Agents that fail to parse are reported in `errors` rather than failing the request. The browsable HTML page is at `/agents`. ```bash theme={"system"} curl "http://127.0.0.1:12233/api/agents" ``` ```json theme={"system"} { "success": true, "agents": [ { "projectId": "projA", "path": "daily.agentuse", "name": "Daily Digest", "description": "Posts a daily digest", "model": "anthropic:claude-sonnet-5", "schedule": "0 9 * * *" } ], "errors": [] } ``` `description` and `schedule` are present only when the agent declares them. #### GET /api/agents/detail Returns the capability summary and raw `.agentuse` source for one loaded agent. The endpoint is operator-gated like the rest of `/api/*`, and `path` must match an agent already loaded by the project. ```bash theme={"system"} curl "http://127.0.0.1:12233/api/agents/detail?project=projA&path=daily.agentuse" \ -H "Authorization: Bearer $AGENTUSE_API_KEY" ``` The browsable agent detail hub is at `/agents//`. #### GET /api/schedules Lists the scheduled agents currently registered with the running daemon as JSON, sorted by next run (soonest first, disabled last). The browsable HTML page is at `/schedules`. ```bash theme={"system"} curl "http://127.0.0.1:12233/api/schedules" ``` ```json theme={"system"} { "success": true, "schedules": [ { "id": "3252d076-d203-4921-b1c4-013d8748406b", "projectId": "projA", "agentPath": "daily.agentuse", "expression": "0 9 * * *", "human": "Daily 9am", "timezone": "America/Vancouver", "enabled": true, "jitterMs": 78721, "nextRun": "2026-06-03T16:00:00.000Z", "lastRun": null, "createdAt": "2026-06-02T21:00:42.371Z" } ] } ``` `nextRun` and `lastRun` are ISO timestamps (or `null`). `lastResult` is included once a scheduled run has completed, and carries the run's `sessionId` so the dashboard can deep-link to its log. #### GET /api/sessions Lists top-level runs as JSON, live first and then by most recent activity. Filters: `?agent=`, `?trigger=scheduled|manual|slack|api`, and `?window=<1h|6h|24h|7d|30d|90d|all>` (default `24h`). Time windows use the last update, so a recently completed long-running session remains visible. The browsable HTML page is at `/sessions`. `?status=incomplete` matches only runs blocked on a person; incomplete runs with any other blocker are listed under `error`. Use `?status=idle` for successful checks with no action due, or `?status=completed` for Done runs excluding idle. Idle rows retain the durable `status: "completed"` and carry `outcome: "idle"`; the list's `counts.idle` and `counts.done` are separate. Older recorded idle outcomes are recovered from the structured tool call. Runs that reported complete are not reclassified from their output text. ```bash theme={"system"} curl "http://127.0.0.1:12233/api/sessions?agent=daily&trigger=scheduled" \ -H "Authorization: Bearer $AGENTUSE_API_KEY" ``` ```json theme={"system"} { "success": true, "sessions": [ { "project": "projA", "sessionId": "01JFN8K3M2P1", "agent": { "id": "daily", "name": "Daily Digest", "description": "Posts a daily digest" }, "status": "completed", "trigger": "scheduled", "createdAt": 1717430400000, "updatedAt": 1717430412000 } ], "window": { "value": "24h", "hours": 24, "updatedAfter": 1717344000000 }, "errors": [] } ``` `trigger` is `scheduled`, `api`, `slack`, or `manual` (CLI runs and the default). For large histories, opt into cursor pagination with `limit` (maximum 100) and the opaque `nextCursor` returned by the prior response: ```bash theme={"system"} curl "http://127.0.0.1:12233/api/sessions?limit=50" ``` Supplying `limit` changes only the list length and adds `limit` and (when more records exist) `nextCursor`; requests without it retain the complete legacy response. Cursors are bound to the active filters and should be treated as opaque. #### GET /api/sessions/:id Returns one session including its run-log entries (`logs`). API-key gated. The human-facing view + approve page is `/sessions/:id`; see [Approval Gates](/guides/approval-gates#experimental-session--approval-api). | Error Code | HTTP Status | Description | | - | - | - | | `NOT_FOUND` | 404 | Endpoint not found (use `POST /api/run` or `GET /api`) | | `AGENT_NOT_FOUND` | 404 | Agent file doesn't exist | | `PROJECT_NOT_FOUND` | 404 | Unknown project id in multi-project mode | | `PROJECT_REQUIRED` | 400 | Multi-project request without `project` or `--default` | | `INVALID_PATH` | 400 | Agent path outside project root | | `INVALID_REQUEST` | 400 | Invalid JSON body | | `MISSING_FIELD` | 400 | Required field missing | | `TIMEOUT` | 504 | Agent execution timed out | | `EXECUTION_ERROR` | 500 | Runtime error during execution | | `INTERNAL_ERROR` | 500 | Unexpected server error | ### Streaming Response For real-time output, request NDJSON streaming by setting the `Accept` header: ```bash theme={"system"} curl -N -X POST http://127.0.0.1:12233/api/run \ -H "Content-Type: application/json" \ -H "Accept: application/x-ndjson" \ -d '{"agent": "my-agent.agentuse"}' ``` Each line is a JSON object representing an execution event: ```json theme={"system"} {"type": "text", "text": "Analyzing..."} {"type": "tool-call", "name": "read_file", "args": {"path": "data.txt"}} {"type": "tool-result", "name": "read_file", "result": "..."} {"type": "text", "text": "Complete!"} {"type": "finish", "finishReason": "end-turn", "duration": 2345} ``` ### Examples ```bash theme={"system"} # Start server with defaults (127.0.0.1:12233) agentuse serve # Start on custom port agentuse serve --port 8080 # Bind to all interfaces (for external access) agentuse serve --host 0.0.0.0 --port 3000 # Set the public URL used in approval review links agentuse serve --public-url https://agentuse.mycompany.com # Provide Slack credentials for agents that enable Slack channels SLACK_BOT_TOKEN=xoxb-... SLACK_APPROVAL_CHANNEL=C0123456789 agentuse serve # Serve agents from a project or subdirectory agentuse serve -C /path/to/project-or-subdir # Host multiple projects from one process agentuse serve -C ./projA -C ./projB # Default POST /api/run to projA when `project` is omitted agentuse serve -C ./projA -C ./projB --default projA # Start with debug logging agentuse serve --debug ``` **API Usage Examples:** ```bash theme={"system"} # Run an agent (JSON response) curl -X POST http://127.0.0.1:12233/api/run \ -H "Content-Type: application/json" \ -d '{"agent": "agents/assistant.agentuse"}' # Run with additional prompt curl -X POST http://127.0.0.1:12233/api/run \ -H "Content-Type: application/json" \ -d '{"agent": "agents/writer.agentuse", "prompt": "Write about AI"}' # Override model curl -X POST http://127.0.0.1:12233/api/run \ -H "Content-Type: application/json" \ -d '{"agent": "agents/helper.agentuse", "model": "openai:gpt-5.4-mini"}' # Streaming response curl -N -X POST http://127.0.0.1:12233/api/run \ -H "Content-Type: application/json" \ -H "Accept: application/x-ndjson" \ -d '{"agent": "agents/analyzer.agentuse"}' # Multi-project: pick which project runs the agent curl -X POST http://127.0.0.1:12233/api/run \ -H "Content-Type: application/json" \ -d '{"project": "projA", "agent": "assistant.agentuse"}' # Discovery: list served projects curl http://127.0.0.1:12233/ ``` ### Scheduled Agents Agents with a `schedule` config in their frontmatter are automatically executed on schedule: ```yaml theme={"system"} --- model: anthropic:claude-sonnet-5 schedule: "1h" --- ``` See the complete guide for intervals and cron expressions. The server enables CORS by default. For production, run behind a reverse proxy with authentication. ### serve ps Show the running `agentuse serve` daemon. ```bash theme={"system"} agentuse serve ps [--json] ``` Shows PID, port, every served project, total agent/schedule counts, and uptime. Multi-project daemons render one project per row under the same daemon. ``` PID PORT PROJECTS AGENTS SCHEDULES UPTIME ──────────────────────────────────────────────────────────────────────────── 63398 12233 projA 12 3 2h 15m projB projC ``` Use `--json` for scripting. Stale entries are automatically cleaned up. While `serve ps` shows counts across daemons, use `serve agents` and `serve schedules` to inspect what a single running daemon actually loaded. ### serve agents List the agents loaded by the running daemon (queries its live `GET /api/agents` endpoint). ```bash theme={"system"} agentuse serve agents [pid] [--json] ``` ``` AGENT NAME MODEL SCHEDULE ──────────────────────────────────────────────────────────────────── adhoc.agentuse Adhoc Helper anthropic:claude-haiku-4-5 — daily.agentuse Daily Digest anthropic:claude-sonnet-5 0 9 * * * ``` Omit `pid` when only one daemon is running. Agents that failed to parse are listed after the table. Use `--json` for the raw payload. When the daemon requires an API key, set `AGENTUSE_API_KEY` so the command can authenticate. ### serve schedules List the scheduled agents in the running daemon (queries its live `GET /api/schedules` endpoint), sorted by next run. ```bash theme={"system"} agentuse serve schedules [pid] [--json] ``` ``` NEXT RUN AGENT SCHEDULE LAST RUN ────────────────────────────────────────────────── Jun 03, 09:00 daily.agentuse Daily 9am never ``` *** ## agentuse schedules Inspect and control deployment-local schedule state without changing agent frontmatter. ```bash theme={"system"} agentuse schedules agentuse schedules pause agentuse schedules resume ``` `agentuse schedules` lists declared schedules and whether each one is active or paused. `pause` and `resume` persist the override for the current deployment and notify a running daemon, when present. The declared cron expression or interval stays in the agent file and remains visible in the dashboard. *** ## agentuse models List the recommended models, the aliases they can be reached by, and your configured default. ```bash theme={"system"} agentuse models # recommended lineup + aliases agentuse models anthropic # one provider agentuse models --all # every model in the registry agentuse models --verbose # context limits, capabilities, alias per model ``` The **Version aliases** section shows what each version-less id (`anthropic:claude-sonnet`) resolves to right now. **Your aliases** and **Default model** appear when a `models` block is configured (see [Configuration Files](/reference/configuration-files#model-defaults-and-aliases)). ### models unpin Replace pinned model versions in agent files with version aliases, so those files track the newest release and stop needing edits: ```bash theme={"system"} agentuse models unpin --dry-run # preview, current directory agentuse models unpin ./agents # apply to a directory agentuse models unpin one.agentuse # apply to a single file ``` ``` agents/researcher.agentuse anthropic:claude-sonnet-5 → anthropic:claude-sonnet (currently anthropic:claude-sonnet-5) ``` ### models bump Move superseded pins forward to the current model of the same product line, for files you want to keep pinned: ```bash theme={"system"} agentuse models bump --dry-run agentuse models bump ./agents ``` Both commands only rewrite model references inside an agent file's YAML frontmatter. Instructions below the frontmatter are left alone, since prose may legitimately name a specific model version. Version aliases are never rewritten by `bump`: they already track the line. *** ## agentuse plugins Install and manage trusted AgentUse packages from Git repositories. ```bash theme={"system"} agentuse plugins install owner/repository agentuse plugins install git:github.com/owner/repository@v1 agentuse plugins list [--json] [--all-scopes] agentuse plugins update [name] agentuse plugins remove agentuse plugins uninstall # alias ``` Add `-l` to any subcommand to use project-local package settings. `install` accepts `owner/repo`, `github:owner/repo`, `git:github.com/owner/repo@ref`, HTTPS or SSH GitHub URLs, and local directory paths (linked in place rather than cloned). `update` without a name updates every plugin in the selected scope, and reports "already up to date" for a pinned source or unchanged linked package. The shorter `agentuse install|update|list|remove` commands remain as compatibility aliases. *** ## agentuse provider Manage providers and authentication credentials. (`auth` still works as a hidden alias.) ### provider login ```bash theme={"system"} agentuse provider login [provider] # built-ins plus installed provider plugins agentuse provider login opencode-go ``` Amazon Bedrock authenticates via standard AWS environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, optional `AWS_SESSION_TOKEN`) or `AWS_BEARER_TOKEN_BEDROCK`. There is no `provider login bedrock` command. ### provider add Add a custom OpenAI-compatible endpoint from the CLI (Ollama, LM Studio, vLLM, etc.). The dashboard can additionally configure OpenAI Responses and Anthropic Messages endpoints; see [Model Configuration](/guides/model-configuration#custom-providers). ```bash theme={"system"} agentuse provider add ollama --url http://localhost:11434/v1 agentuse provider add lmstudio --url http://localhost:1234/v1 agentuse provider add myserver --url https://gpu.example.com/v1 --key sk-mykey ``` Then use: `agentuse run agent.agentuse -m ollama:glm-5-flash:q4_K_M` The command prints `URL`, `API`, `Key`, and `Models` lines. Each URL and key is labelled `stored` or `from _BASE_URL` / `from _API_KEY` when an environment variable overrides it. Colons in model names are supported, `ollama:qwen3.5:0.8b` parses as provider `ollama`, model `qwen3.5:0.8b`. ### provider remove / logout ```bash theme={"system"} agentuse provider remove ollama # remove custom provider agentuse provider logout openai # remove built-in credentials ``` ### provider list ```bash theme={"system"} agentuse provider list agentuse provider list --json # machine-readable status; never includes secrets ``` ## agentuse mcp Manage logins for the HTTP MCP servers an agent uses. See [OAuth MCP Servers](/reference/agent-syntax#oauth-mcp-servers) for the agent-file side. ```bash theme={"system"} agentuse mcp login # Log in; every agent using the same server URL shares it agentuse mcp login --no-browser # Print the login URL instead of opening a browser agentuse mcp status # Show how each of the agent's MCP servers signs in agentuse mcp logout # Forget the saved login ``` `` is the agent file and `` is the server's name under `mcpServers`. *** ## agentuse skills List and retrieve AgentUse builtin skills that ship with the installed CLI version. Use the `installed` subcommand to inspect project and user-installed skills. ### Syntax ```bash theme={"system"} agentuse skills [subcommand] [options] ``` ### Subcommands ```bash theme={"system"} agentuse skills # List AgentUse builtin skills agentuse skills list # Explicit builtin list command agentuse skills get # Output builtin skill content agentuse skills get --full agentuse skills get --all # Output every builtin skill agentuse skills path [name] # Print builtin skill paths agentuse skills installed # List installed/discovered skills agentuse skills installed get agentuse skills installed path [name] ``` ### Options ```bash theme={"system"} -v, --verbose Show skill file paths and tool requirements when listing -j, --json Output machine-readable JSON --full Include supporting files when using get --all Output every skill for the selected source when using get ``` ### Builtin Skills Builtin skills are stored in the AgentUse package `skill-data/` directory and match the installed CLI version. This mirrors the `agent-browser skills` model: agents can fetch current official instructions without reading a user's entire local skill library. | Skill | Covers | | - | - | | `core` | The entry point: what AgentUse is, and which of the three below to fetch next | | `runner` | Running agents, listing them, sessions, `serve`, schedules | | `creator` | Authoring, improving, and reviewing `.agentuse` files | | `tester` | Validating agents without real side effects: choosing a mock model and scope, exercising approval gates unattended, the edit-run-inspect loop, and the fidelity caveats of mock output | ### AI Coding Assistants Install the assistant-facing AgentUse skill stub: ```bash theme={"system"} npx skills add agentuse/agentuse ``` For local development, install from this checkout: ```bash theme={"system"} npx skills add . ``` This installs the thin `agentuse` skill from `skills/agentuse/SKILL.md`. The stub points assistants at `agentuse skills get core`, so the real workflow guidance stays version-aligned with the installed AgentUse CLI. ### Installed Skill Locations Installed skills are discovered from these directories (in priority order): 1. `.agentuse/skills/` - Project-specific skills 2. `$AGENTUSE_CONFIG_DIR/skills/` - User-global skills (defaults to `~/.agentuse/skills/`) 3. `.claude/skills/` - Claude ecosystem compatibility 4. `~/.claude/skills/` - Claude ecosystem compatibility 5. `~/.agents/skills/` - Shared agent skills compatibility Symlinked skill directories and `SKILL.md` files are supported. AgentUse skips dangling links, resolves directory real paths, and avoids circular traversal. ### Examples ```bash theme={"system"} # List AgentUse builtin skills agentuse skills agentuse skills list # Show verbose output with file paths and tool requirements agentuse skills -v agentuse skills --verbose # Return machine-readable metadata agentuse skills --json agentuse skills list --json # Print builtin skill content for an agent or script agentuse skills get core agentuse skills get runner agentuse skills get creator agentuse skills get tester agentuse skills get core --full agentuse skills get --all --json # Print builtin paths agentuse skills path agentuse skills path core # Inspect project and user-installed skills agentuse skills installed agentuse skills installed list --json agentuse skills installed get code-review agentuse skills installed get code-review --full agentuse skills installed path code-review ``` ### Output Example ``` Found 3 builtin skill(s): agentuse builtins core Core AgentUse usage guide... creator Create, improve, and review AgentUse agent files... runner Run and manage AgentUse agents from the CLI... ``` Installed skills: ``` Found 2 installed skill(s): .agentuse/skills code-review Review code for quality, security, and maintainability... ``` With verbose mode (`-v`): ``` Found 2 installed skill(s): .agentuse/skills code-review Review code for quality, security, and maintainability... /path/to/project/.agentuse/skills/code-review/SKILL.md tools: Read, Bash(git:*) ``` For detailed information on creating and using skills, see the [Skills Guide](/guides/skills). *** ## agentuse doctor Diagnose an agent's skill capability configuration. Static mode inspects the agent file; `--last-run` inspects the most recent recorded session. ### Syntax ```bash theme={"system"} agentuse doctor [--last-run] ``` ### What It Checks Static mode: * Recurring prompt cost per model request: the agent body, the full text of each preloaded skill, and the visible skill catalog, with a total. * Explicit skills that don't exist on disk. * Explicit skills with no `allow` grants. * Commands mentioned in skill docs vs. what the agent has granted (advisory; not a permission manifest). * Learnings: how many of the stored ones are actually applied per run, and how many are over `learning.max` and so never reach the model, with `agentuse learnings tidy ` as the fix. It also reports how many are **stale** (the agent instructions changed since they were vetted, so they are held out of injection until the next capture or tidy re-vets them), a `by channel:` breakdown of what captured them (`corrections`, `tool-errors`, `custom`, `agent`, or `legacy` for entries predating channels), and every **quarantined** entry with the reason it failed the vet. It prints the resolved `learnings file:` path, echoes any one-time notice about a legacy `learning:` form, and warns when learnings are still sitting beside the agent file at the pre-0.17.0 location where nothing reads them. `--last-run` mode: * Finds the latest non-subagent session for this agent. * Reports blocked bash commands from runtime and prints a suggested `tools.bash.commands` snippet. ### Examples ```bash theme={"system"} # Static inspection agentuse doctor agents/research.agentuse # Diagnose actual blocked commands from the last run agentuse doctor agents/research.agentuse --last-run ``` ### Prompt Size Warnings Two costs recur on **every** model request, so doctor flags them: | What | Warns above | Warns harder above | | - | - | - | | Preloaded skills (the full text of everything in `skills:`) | \~2,000 tokens | \~4,000 tokens | | Visible skill catalog (a name and description per discoverable skill) | \~1,500 tokens | \~3,000 tokens | The fix for either is the same shape: preload only what every run needs, and close discovery with `skills.auto: false` plus a shorter explicit list. Open discovery is the expensive default at scale, a machine with 100 skills installed pays roughly 11k tokens per request for the catalog alone. Use `--last-run` after an agent fails or behaves unexpectedly. It uses real tool errors and is more accurate than static skill-doc extraction. *** ## agentuse learnings Inspect and tidy an agent's stored learnings. Only the top few apply per run (15 by default, `learning.max`); anything past that is stored but never reaches the model, and so are entries that are quarantined (failed the vet) or stale (the agent instructions changed since they were vetted). See the [Learning guide](/guides/learning). ### Syntax ```bash theme={"system"} agentuse learnings [--json] [--path] [--edit] agentuse learnings tidy [--dry-run] [--model ] agentuse learnings undo agentuse learnings migrate [|--all] [--dry-run] [--keep-source|--delete-source] ``` ### Subcommands | Command | Description | | - | - | | *(none)* | List every learning by status: applied, never reaches the agent, stale (instructions changed, awaiting re-vet), quarantined (failed the vet, with the reason), in the agent file, retired. | | `tidy` | Re-vet every learning the agent instructions have moved out from under, merge near-duplicates, sharpen learnings you have repeated, retire what is superseded, and make proven learnings permanent in the agent file. Applies immediately, then shows both diffs. Keeps making passes until another one would not help, up to five, and writes both files once at the end, so one run is one undo. Says what it is doing as it goes: a long list takes a few minutes. If it ends still over the cap, it accounts for every learning it left in force. | | `undo` | Restore the learnings file **and** the agent file to their state before the last tidy-up, including anything that pass quarantined. | | `migrate` | Move learnings written before v0.17.0 from beside the agent file into the AgentUse state directory. Copies first, then asks once before deleting the originals; refuses a destination that already holds learnings rather than merging; also lists any `*.learnings.md` with no matching agent file as orphaned. | ### Options | Option | Description | | - | - | | `-j, --json` | Machine-readable listing. Top level: `file` (the resolved learnings path), `cap`, and `active` / `injected` / `dormant` / `stale` / `quarantined` counts. Each entry in `learnings` carries its full record, including `channel`, `injectedCount`, `approvedRuns`, `instructionsHash`, and `quarantineReason`, plus a resolved `state` and computed `injected` and `stale` flags. | | `--path` | Print the path of the learnings file and exit. | | `--edit` | Open the learnings file in `$EDITOR` (or `$VISUAL`), creating its directory if needed. | | `--dry-run` | (`tidy`) Show the plan and both diffs without writing anything. (`migrate`) Report what would move, including refusals, without writing anything. | | `--model ` | (`tidy`) Plan with this model instead of the agent's own. | | `--all` | (`migrate`) Every agent file in the project, not one named agent. | | `--keep-source` | (`migrate`) Keep the old files without asking. | | `--delete-source` | (`migrate`) Delete the old files without asking. Required to delete anything when stdin is not a terminal, a non-interactive run never deletes on its own. | ### Examples ```bash theme={"system"} # What is actually reaching this agent? agentuse learnings agents/blog-writer.agentuse # Where does this agent's learnings file live? agentuse learnings agents/blog-writer.agentuse --path # See what a tidy-up would do, then do it agentuse learnings tidy agents/blog-writer.agentuse --dry-run agentuse learnings tidy agents/blog-writer.agentuse # Changed your mind agentuse learnings undo agents/blog-writer.agentuse # Upgrading from before v0.17.0 agentuse learnings migrate --all --dry-run agentuse learnings migrate --all git commit -am "chore: move learnings to the agentuse state dir" ``` A tidy-up writes proven learnings into a marked block in your `.agentuse` file. Only the bytes inside the markers change, frontmatter, comments and formatting are left exactly as they were, and `undo` restores both files byte for byte. Learnings no longer live beside your agent file. As of v0.17.0 they live under the AgentUse state directory, and the old location is never read. Run `agentuse learnings migrate --all` once per repo to copy them across; it will ask before removing the originals. `migrate` exits non-zero if it refused any file. *** ## agentuse agents Discover and list all agent files in the current project. ### Syntax ```bash theme={"system"} agentuse agents [options] ``` ### Options ```bash theme={"system"} -v, --verbose Show agent file paths ``` ### Examples ```bash theme={"system"} # List all agents in the project agentuse agents # Show verbose output with file paths agentuse agents -v ``` ### Output Example ``` Found 3 agent(s): agents/ assistant General-purpose AI assistant code-reviewer Reviews code for quality and security researcher Researches topics and summarizes findings ``` *** ## agentuse add Add skills and agents from GitHub repos or local paths. ### Syntax ```bash theme={"system"} agentuse add [options] ``` ### Arguments Source to add. Supports: * GitHub shorthand: `user/repo` or `user/repo#branch` * Git URL: `https://github.com/user/repo.git` * Local path: `./path/to/repo` * Direct skill: `./path/to/skill` (directory containing SKILL.md) ### Options ```bash theme={"system"} --force Overwrite existing skills/agents without prompting --all Install all skills and agents without prompting --list List available skills and agents without installing -s, --skill Install specific skill(s) by name (repeatable) -a, --agent Install specific agent(s) by path (repeatable) ``` `--skill` and `--agent` install exactly the named items: `--skill` alone installs no agents, and `--agent` alone installs no skills. Combine them to install both. ### What Gets Added | Source Pattern | Destination | | - | - | | `**/SKILL.md` (parent dir) | `.agentuse/skills/{skill-name}/` | | `SKILL.md` at the source root | `.agentuse/skills/{repo-or-directory-name}/` | | `**/*.agentuse` | Same relative path in project | ### Examples ```bash theme={"system"} # Add from GitHub (interactive selection) agentuse add vercel-labs/agent-skills agentuse add vercel-labs/agent-skills#v1.0.0 # List available skills/agents without installing agentuse add vercel-labs/agent-skills --list # Install specific skills agentuse add vercel-labs/agent-skills --skill react-best-practices agentuse add vercel-labs/agent-skills -s skill-a -s skill-b # Install specific agents agentuse add user/repo --agent deploy.agentuse # Install all without prompting agentuse add user/repo --all # Overwrite existing without prompting agentuse add user/repo --force # Add from local path agentuse add ./my-skills-repo agentuse add ./path/to/single-skill ``` ### Conflict Handling When a skill or agent already exists, you'll be prompted: ``` Skill "my-skill" already exists. [s] Skip [o] Overwrite [a] Skip all [O] Overwrite all ``` *** ## agentuse setup First-run setup. Run it without flags in a terminal to choose how to continue: * **Mac app** (Apple silicon only): opens `https://agentuse.io/download/mac`. The app includes its own runtime. * **Browser**: starts `agentuse serve` and opens the guided setup in the Web UI. * **Terminal**: creates your first project and prints the next steps. ```bash theme={"system"} agentuse setup agentuse setup --terminal --name my-agents --yes ``` Options: ```bash theme={"system"} --web Continue setup in the Web UI --terminal Continue setup in the terminal --name Managed project name (terminal) -y, --yes Accept the default project name without prompting -p, --port Web setup server port (default: 12233) -H, --host Web setup server host (default: 127.0.0.1) --no-auth Disable server API key requirement (dangerous on publicly reachable hosts) ``` `--name` and `--yes` imply `--terminal`; `--web` cannot be combined with them. Without a terminal, pass `--web` or `--terminal`. ## agentuse help Show help information. ### Syntax ```bash theme={"system"} agentuse --help agentuse -h # Command-specific help agentuse run --help agentuse auth --help ``` ### Examples ```bash theme={"system"} # General help agentuse --help # Command-specific help agentuse run --help agentuse auth --help # Show help when no arguments provided agentuse ``` The `agentuse config` command is not yet implemented. Configuration is currently managed through environment variables only. ## Global Options ```bash theme={"system"} --version Show version number --help, -h Show help for command ``` ## Environment Variables Control AgentUse behavior with environment variables. See [Environment Variables Reference](/reference/environment-variables) for complete documentation. ## Exit Codes AgentUse uses standard exit codes: | Code | Meaning | | - | - | | 0 | Success | | 1 | General error, including an `incomplete` run (exit 0 only when the blocker is a person: `waiting_on_human` or `rejected_by_human`) | | 2 | Authentication error | | 3 | File not found | | 4 | Model error | | 5 | Tool error | | 6 | MCP error | | 7 | Network error | | 130 | User interrupted (Ctrl+C) | ## Available Commands AgentUse currently supports these commands: ```bash theme={"system"} agentuse run [prompt...] # Run an agent with optional prompt agentuse test workflow # Check steps with simulated tool responses agentuse test result --session # Compare results using a past job’s evidence agentuse serve [options] # Start the HTTP daemon to run agents via API agentuse serve ps [--json] # Show the running serve daemon agentuse serve schedules [pid] [--json] # List schedules the running daemon is tracking agentuse serve agents [pid] [--json] # List agents the running daemon has loaded agentuse sessions [list|show|resume|path] # View and resume sessions agentuse sessions reconcile [--all] # Settle runs stuck at "running" agentuse sessions backfill-blockers # Add blockers to older incomplete runs agentuse setup [--web|--terminal] # First-run setup in the Mac app, browser, or terminal agentuse provider login [provider] # Authenticate with a provider agentuse provider add --url # Add custom provider (Ollama, LM Studio, etc.) agentuse provider logout [provider] # Remove stored credentials agentuse provider remove # Remove a custom provider agentuse provider list # Show all providers and credentials agentuse provider help # Show detailed auth help agentuse mcp login # Log in to an OAuth MCP server agentuse mcp status # Show how an agent's MCP servers sign in agentuse mcp logout # Forget an MCP server login agentuse models [provider] [options] # List models, aliases, and the configured default agentuse models unpin [path] # Swap pinned model versions for version aliases agentuse models bump [path] # Move superseded pins to the current model agentuse skills [subcommand] [options] # List/get builtin or installed skills agentuse doctor [--last-run] # Diagnose agent skill capability config agentuse learnings [--json] # List an agent's stored learnings by status agentuse learnings --path # Print where the learnings file lives agentuse learnings tidy # Merge, sharpen, retire and make proven ones permanent agentuse learnings undo # Restore both files to their pre-tidy state agentuse learnings migrate --all # Move pre-0.17.0 learnings into the state directory agentuse agents [options] # Discover and list project agents agentuse add [options] # Add skills/agents from GitHub or local path agentuse --version # Show version agentuse --help # Show help ``` The `agentuse auth` command still works as a backward-compatible alias for `agentuse provider`. ## Advanced Usage ### Piping ```bash theme={"system"} # Pipe input to agent echo "Translate this to Spanish" | agentuse run translator.agentuse # Pipe agent output agentuse run generator.agentuse | tee output.txt # Chain agents agentuse run analyzer.agentuse < data.txt | agentuse run summarizer.agentuse ``` ### Shell Integration ```bash theme={"system"} # Bash function agent() { agentuse run "$1.agentuse" "${@:2}" } # Usage agent translator "Hello world" ``` ### Batch Processing ```bash theme={"system"} # Process multiple files for file in *.txt; do agentuse run processor.agentuse < "$file" > "processed_$file" done # Parallel processing find . -name "*.md" | parallel agentuse run formatter.agentuse {} ``` ## Troubleshooting Ensure AgentUse is installed globally: ```bash theme={"system"} pnpm install -g agentuse ``` On Unix systems, you may need sudo: ```bash theme={"system"} sudo pnpm install -g agentuse ``` If you see authentication errors, AgentUse will show specific guidance: ```bash theme={"system"} [ERROR] No API key found for anthropic To authenticate, run: agentuse provider login Or set your API key: export ANTHROPIC_API_KEY='your-key-here' For more options: agentuse provider --help ``` Increase timeout for long-running agents: ```bash theme={"system"} agentuse run agent.agentuse --timeout 600 # or via environment MAX_STEPS=2000 agentuse run agent.agentuse ``` Enable debug output: ```bash theme={"system"} agentuse run agent.agentuse --debug ``` ## Next Steps Learn agent file format Create your first agent This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.