AgentUse - Autonomous Agents That Work Without You

agentuse run

Execute an agent file.

Syntax

agentuse run <agent-file> [prompt...] [options]

Arguments

agent-file

string

required

Path to agent file (.agentuse or .md extension) or HTTPS URL

prompt

string

Optional additional prompt to append to the agent’s instructions

Options

-q, --quiet             Suppress info messages (only show warnings/errors)
-d, --debug             Enable verbose debug logging
--no-tty                Disable TUI output (plain logs for piping/automation)
-v, --verbose           Show detailed execution information
--timeout <seconds>     Maximum execution time in seconds (default: 300)
-C, --directory <path>  Run as if agentuse was started in <path> instead of the current directory
--env-file <path>       Path to custom .env file
-m, --model <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>    Model that generates mock tool outputs (required with --mock; pick a cheap, reachable model)
--mock-approval         Also mock the await_human approval gate instead of suspending

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:

# 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 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)
env: Optional environment suffix for API keys (e.g., dev, prod, or full env var name) — built-in providers only

Examples

# Override with OpenAI GPT-5
agentuse run agent.agentuse --model openai:gpt-5.5
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

# Use different API key via environment suffix
agentuse run agent.agentuse --model openai:gpt-5.5: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.

Model overrides propagate to all sub-agents. When you use --model, both the parent agent and all its sub-agents will use the specified model, regardless of what models are defined in their individual agent files.

Testing with Mocked Tools

--mock runs an agent with no real tool side effects: each tool call is answered by an LLM-generated result instead of executing. The agent runs for real; only tool execution is faked.

agentuse run agent.agentuse --mock --mock-model anthropic:claude-haiku-4-5
agentuse run agent.agentuse --mock --mock-model openai:gpt-5.4-nano

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 429s. 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. The flag wins over all of them.
Sub-agents run for real; their leaf tools are mocked.
The approval gate stays real: await_human still suspends so you can verify the agent pauses for approval. Pass --mock-approval to mock it too.

MCP servers still connect at startup for tool discovery, but no tool executes (no mutations). Mock outputs are non-deterministic.

Remote Agent Security

When running agents from remote URLs:

HTTPS Only: Only HTTPS URLs are allowed for security
File Extension: Remote agents must have .agentuse extension
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

# 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.5:dev

# Override model for agent with sub-agents (all will use the same model)
agentuse run orchestrator.agentuse --model openai:gpt-5.4-mini

agentuse sessions

View and resume AgentUse sessions.

Syntax

agentuse sessions list [options]
agentuse sessions show <id> [options]
agentuse sessions resume <id> [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

agentuse sessions list
agentuse sessions list --all
agentuse sessions list --project ../other-project

List options:

-s, --subagents          Include subagent sessions
-n, --limit <n>          Limit number of sessions to show
-j, --json               Output as JSON
--all                    Show sessions across all projects
--project [path]         Show sessions for a project path; defaults to current project

Show a Session

agentuse sessions show 01K...
agentuse sessions show 01K... --all-search
agentuse sessions show 01K... --project ../other-project

Show options:

-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:

agentuse sessions resume 01K... --approve
agentuse sessions resume 01K... --approve "Looks good"
agentuse sessions resume 01K... --reject "Not ready"
agentuse sessions resume 01K... --comment "Please revise the CTA"

The CLI uses local session access as the trust boundary, so approval resumes do not require a resume token. For a suspended non-approval await_* tool:

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:

agentuse sessions resume 01K... --prompt "Continue from here and add tests"

Resume options:

-C, --directory <path>   Run as if agentuse was started in <path>
--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

Show Storage Path

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

agentuse serve [options]

Options

-p, --port <number>     Port to listen on (default: 12233)
-H, --host <string>     Host to bind to (default: 127.0.0.1)
-C, --directory <path>  Directory to serve agents from; project state is detected upward
--default <id>          Default project for POST /api/run when `project` is omitted
-d, --debug             Enable debug mode
--no-auth               Disable API key requirement for exposed hosts (dangerous)
--no-log-file           Disable writing serve logs to a file

Serving Multiple Projects

AgentUse runs one serve daemon at a time. Repeat -C on that daemon to serve multiple scopes/projects:

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 <id> 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 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:

# 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:

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.)

{
  "version": "0.12.0",
  "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 }
  ]
}

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:

{
  "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):

{
  "success": true,
  "result": {
    "text": "Agent response text",
    "finishReason": "end-turn",
    "duration": 1234,
    "tokens": { "input": 500, "output": 200 },
    "toolCalls": 3
  }
}

Error Response:

{
  "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.

curl "http://127.0.0.1:12233/api/agents"

{
  "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.

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/<project>/<agent-path>.

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.

curl "http://127.0.0.1:12233/api/schedules"

{
  "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 every run (top-level sessions only) as JSON, newest first. Filters: ?agent=<id>, ?trigger=scheduled|manual|slack|api, ?days=<n|all> (default ~7 days). The browsable HTML page is at /sessions.

curl "http://127.0.0.1:12233/api/sessions?agent=daily&trigger=scheduled" \
  -H "Authorization: Bearer $AGENTUSE_API_KEY"

{
  "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": { "days": 7, "createdAfter": 1716825600000 },
  "errors": []
}

trigger is scheduled, api, slack, or manual (CLI runs and the default).

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.

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:

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:

{"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

# 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:

# 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:

---
model: anthropic:claude-sonnet-5
schedule: "1h"
---

Scheduled Agents Guide

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.

agentuse serve ps [--json]

Shows PID, port, project summary, total agent/schedule counts, and uptime. Multi-project daemons show the first project id plus +N additional projects.

PID      PORT     PROJECTS                       AGENTS   SCHEDULES   UPTIME
────────────────────────────────────────────────────────────────────────────
63398    12233    projA +2                       12       3           2h 15m

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).

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.

agentuse serve schedules [pid] [--json]

NEXT RUN       AGENT           SCHEDULE   LAST RUN
──────────────────────────────────────────────────
Jun 03, 09:00  daily.agentuse  Daily 9am  never

agentuse provider

Manage providers and authentication credentials. (auth still works as a hidden alias.)

agentuse provider login [provider]   # anthropic, openai, openrouter, opencode-go
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 (Ollama, LM Studio, vLLM, etc.).

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

Colons in model names are supported — ollama:qwen3.5:0.8b parses as provider ollama, model qwen3.5:0.8b.

provider remove / logout

agentuse provider remove ollama       # remove custom provider
agentuse provider logout openai       # remove built-in credentials

provider list

agentuse provider list

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

agentuse skills [subcommand] [options]

Subcommands

agentuse skills                 # List AgentUse builtin skills
agentuse skills list            # Explicit builtin list command
agentuse skills get <name>      # Output builtin skill content
agentuse skills get <name> --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 <name>
agentuse skills installed path [name]

Options

-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.

AI Coding Assistants

Install the assistant-facing AgentUse skill stub:

npx skills add agentuse/agentuse

For local development, install from this checkout:

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):

.agentuse/skills/ - Project-specific skills
~/.agentuse/skills/ - User-global skills
.claude/skills/ - Claude ecosystem compatibility
~/.claude/skills/ - Claude ecosystem compatibility

Examples

# 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 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.

agentuse doctor

Diagnose an agent’s skill capability configuration. Static mode inspects the agent file; --last-run inspects the most recent recorded session.

Syntax

agentuse doctor <file> [--last-run]

What It Checks

Static mode:

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).

--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

# Static inspection
agentuse doctor agents/research.agentuse

# Diagnose actual blocked commands from the last run
agentuse doctor agents/research.agentuse --last-run

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 agents

Discover and list all agent files in the current project.

Syntax

agentuse agents [options]

Options

-v, --verbose    Show agent file paths

Examples

# 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

agentuse add <source> [options]

Arguments

source

string

required

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

--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 <name>   Install specific skill(s) by name (repeatable)
-a, --agent <path>   Install specific agent(s) by path (repeatable)

What Gets Added

Source Pattern	Destination
`**/SKILL.md` (parent dir)	`.agentuse/skills/{skill-name}/`
`*/.agentuse`	Same relative path in project

Examples

# 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 help

Show help information.

Syntax

agentuse --help
agentuse -h
# Command-specific help
agentuse run --help
agentuse auth --help

Examples

# 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.

The agentuse test command is not yet implemented.

Global Options

--version              Show version number
--help, -h            Show help for command

Environment Variables

Control AgentUse behavior with environment variables. See Environment Variables Reference for complete documentation.

Exit Codes

AgentUse uses standard exit codes:

Code	Meaning
0	Success
1	General error
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:

agentuse run <file> [prompt...]          # Run an agent with optional prompt
agentuse serve [options]                 # Start the HTTP daemon to run agents via API
agentuse serve ps [--json]               # Show the running serve daemon
agentuse provider login [provider]       # Authenticate with a provider
agentuse provider add <name> --url <url> # Add custom provider (Ollama, LM Studio, etc.)
agentuse provider logout [provider]      # Remove stored credentials
agentuse provider remove <name>          # Remove a custom provider
agentuse provider list                   # Show all providers and credentials
agentuse provider help                   # Show detailed auth help
agentuse skills [subcommand] [options]   # List/get builtin or installed skills
agentuse doctor <file> [--last-run]      # Diagnose agent skill capability config
agentuse agents [options]                # Discover and list project agents
agentuse add <source> [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

# 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 function
agent() {
  agentuse run "$1.agentuse" "${@:2}"
}

# Usage
agent translator "Hello world"

Batch Processing

# 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

Command not found

Ensure AgentUse is installed globally:

pnpm install -g agentuse

Permission denied

On Unix systems, you may need sudo:

sudo pnpm install -g agentuse

Authentication errors

If you see authentication errors, AgentUse will show specific guidance:

[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

Timeout issues

Increase timeout for long-running agents:

agentuse run agent.agentuse --timeout 600
# or via environment
MAX_STEPS=2000 agentuse run agent.agentuse

Debugging issues

Enable debug output:

agentuse run agent.agentuse --debug

​agentuse run

​Syntax

​Arguments

​Options

​Directory and Path Resolution

​Directory Override (-C, —directory)

​Project Root Detection

​Path Resolution Rules

​Model Override

​Format

​Examples

​Testing with Mocked Tools

​Remote Agent Security

​Examples

​agentuse sessions

​Syntax

​List Sessions

​Show a Session

​Resume a Session

​Show Storage Path

​agentuse serve

​Syntax

​Options

​Serving Multiple Projects

​Global Config

​Authentication

​API Endpoints

​GET /api

​POST /api/run

​GET /api/agents

​GET /api/agents/detail

​GET /api/schedules

​GET /api/sessions

​GET /api/sessions/:id

​Streaming Response

​Examples

​Scheduled Agents

Scheduled Agents Guide

​serve ps

​serve agents

​serve schedules

​agentuse provider

​provider login

​provider add

​provider remove / logout

​provider list

​agentuse skills

​Syntax

​Subcommands

​Options

​Builtin Skills

​AI Coding Assistants

​Installed Skill Locations

​Examples

​Output Example

​agentuse doctor

​Syntax

​What It Checks

​Examples

​agentuse agents

​Syntax

​Options

​Examples

​Output Example

​agentuse add

​Syntax

​Arguments

​Options

​What Gets Added

​Examples

​Conflict Handling

​agentuse help

​Syntax

​Examples

​Global Options

​Environment Variables

​Exit Codes

​Available Commands

​Advanced Usage

​Piping

agentuse run

Syntax

Arguments

Options

Directory and Path Resolution

Directory Override (-C, —directory)

Project Root Detection

Path Resolution Rules

Model Override

Format

Examples

Testing with Mocked Tools

Remote Agent Security

Examples

agentuse sessions

Syntax

List Sessions

Show a Session

Resume a Session

Show Storage Path

agentuse serve

Syntax

Options

Serving Multiple Projects

Global Config

Authentication

API Endpoints

GET /api

POST /api/run

GET /api/agents

GET /api/agents/detail

GET /api/schedules

GET /api/sessions

GET /api/sessions/:id

Streaming Response

Examples

Scheduled Agents

serve ps

serve agents

serve schedules

agentuse provider

provider login

provider add

provider remove / logout

provider list

agentuse skills

Syntax

Subcommands

Options

Builtin Skills

AI Coding Assistants

Installed Skill Locations

Examples

Output Example

agentuse doctor

Syntax

What It Checks

Examples

agentuse agents

Syntax

Options

Examples

Output Example

agentuse add

Syntax

Arguments

Options

What Gets Added

Examples

Conflict Handling

agentuse help

Syntax

Examples

Global Options

Environment Variables

Exit Codes

Available Commands

Advanced Usage

Piping

Shell Integration