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

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, bedrock) or a custom provider name
model: The specific model name (e.g., claude-sonnet-4-6, gpt-5.2, glm-4.7-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

# 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.2: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-4-6: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.

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-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.2:dev

# Override model for agent with sub-agents (all will use the same model)
agentuse run orchestrator.agentuse --model openai:gpt-5-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 /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/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

GET /

Returns version, default project, and served projects.

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

Execute an agent and receive the result. Request Body:

{
  "agent": "path/to/agent.agentuse",
  "project": "projA",
  "prompt": "Optional additional prompt",
  "model": "anthropic:claude-sonnet-4-6",
  "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"
  }
}

Error Code	HTTP Status	Description
`NOT_FOUND`	404	Endpoint not found (use `POST /run` or `GET /`)
`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/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 /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/run \
  -H "Content-Type: application/json" \
  -d '{"agent": "agents/assistant.agentuse"}'

# Run with additional prompt
curl -X POST http://127.0.0.1:12233/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/run \
  -H "Content-Type: application/json" \
  -d '{"agent": "agents/helper.agentuse", "model": "openai:gpt-5-mini"}'

# Streaming response
curl -N -X POST http://127.0.0.1:12233/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/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-4-6
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.

agentuse provider

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

agentuse provider login [provider]   # anthropic, openai, openrouter

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-4.7-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 available skills discovered from the project and user skill directories.

### Syntax

```bash
agentuse skills [options]

Options

-v, --verbose    Show skill file paths and tool requirements

Discovery Locations

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 all available skills
agentuse skills

# Show verbose output with file paths and tool requirements
agentuse skills -v
agentuse skills --verbose

Output Example

Found 2 skill(s):

.agentuse/skills
  code-review
    Review code for quality, security, and maintainability...

~/.agentuse/skills
  seo-analyzer
    Analyze content for SEO optimization...

With verbose mode (-v):

Found 2 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 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 [options]                # List available skills
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

Getting Started

Building

Running

Reference

Documentation Index

​agentuse run

​Syntax

​Arguments

​Options

​Directory and Path Resolution

​Directory Override (-C, —directory)

​Project Root Detection

​Path Resolution Rules

​Model Override

​Format

​Examples

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

​POST /run

​Streaming Response

​Examples

​Scheduled Agents

Scheduled Agents Guide

​serve ps

​agentuse provider

​provider login

​provider add

​provider remove / logout

​provider list

​Options

​Discovery Locations

​Examples

​Output Example

​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

​Batch Processing

​Troubleshooting

​Next Steps

Agent Syntax

Quick Start

agentuse run

Syntax

Arguments

Options

Directory and Path Resolution

Directory Override (-C, —directory)

Project Root Detection

Path Resolution Rules

Model Override

Format

Examples

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 /

POST /run

Streaming Response

Examples

Scheduled Agents

serve ps

agentuse provider

provider login

provider add

provider remove / logout

provider list

Options

Discovery Locations

Examples

Output Example

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

Batch Processing

Troubleshooting

Next Steps