AgentUse - AI Agents as Simple as Markdown

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

Directory and Path Resolution

Directory Override (-C, —directory)

The -C or --directory option changes the working directory before running:

# Without -C: runs from current directory
agentuse run agent.agentuse

# With -C: changes to specified directory first (like cd)
agentuse run agent.agentuse -C /path/to/project

Project Root Detection

AgentUse searches from the current directory upward for .git/, .agentuse/, or package.json. The project root is used for:

Loading .env files
Finding plugins in .agentuse/plugins/

This is useful for:

Running agents from different projects
CI/CD environments with complex directory structures
Testing with different configurations

Path Resolution Rules

For Subagents: Paths are relative to the parent agent file’s directory:

# In /project/agents/main.agentuse
subagents:
  - path: ../utils/helper.agentuse  # Resolves to /project/utils/helper.agentuse

For MCP Servers: Command paths are relative to the agent file’s directory:

# In /project/agents/main.agentuse
mcp_servers:
  custom:
    command: ../tools/my-server  # Resolves to /project/tools/my-server

For Environment Files:

Default: {project-root}/.env
Override: --env-file /path/to/.env

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: Either anthropic or openai
model: The specific model name (e.g., claude-3-5-sonnet-20241022, gpt-4o)
env: Optional environment suffix for API keys (e.g., dev, prod, or full env var name)

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-3-5-haiku-latest

# Use different API key via environment suffix
agentuse run agent.agentuse --model openai:gpt-4o:dev
# This will use OPENAI_API_KEY_DEV instead of OPENAI_API_KEY

# Use specific environment variable
agentuse run agent.agentuse --model anthropic:claude-3-5-sonnet: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

# 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-3-5-haiku-latest

# Use development API key with model override
agentuse run agent.agentuse -m openai:gpt-4o:dev

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

agentuse auth

Manage authentication for AI providers.

Subcommands

Authenticate with a provider.

agentuse auth login [provider]

Providers:

anthropic - Anthropic Claude (supports OAuth)
openai - OpenAI GPT
openrouter - OpenRouter

Examples:

# Interactive login (shows provider selection)
agentuse auth login

# Login to specific provider
agentuse auth login anthropic
agentuse auth login openai
agentuse auth login openrouter

auth logout

Remove stored credentials.

agentuse auth logout [provider]

Examples:

# Logout from all providers
agentuse auth logout

# Logout from specific provider
agentuse auth logout openai

auth list

Show authentication status and stored credentials.

agentuse auth list
# or
agentuse auth ls

Output:

📁 Credentials stored in: ~/.agentuse/auth.json

Stored credentials:
  🔑 anthropic (oauth) → Use as: anthropic:claude-3-5-sonnet-20241022
  🎫 openai (api) → Use as: openai:gpt-4o
  🎫 openrouter (api) → Use as: openrouter:qwen/qwen-2.5-72b-instruct

Environment variables:
  🌍 openai (OPENAI_API_KEY) → Use as: openai:gpt-4o

Model usage examples:
  agentuse run agent.agentuse --model anthropic:claude-3-5-sonnet-20241022
  agentuse run agent.agentuse --model openai:gpt-4o
  agentuse run agent.agentuse --model openrouter:qwen/qwen-2.5-72b-instruct

auth help

Show detailed authentication help and configuration options.

agentuse auth help

Displays comprehensive help including:

Authentication methods (login command vs environment variables)
Provider-specific setup instructions
Environment variable configuration for different shells
Priority order for credential resolution
Links to get API keys

The agentuse create command is not yet implemented. Please create agent files manually using the .agentuse extension.

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:

# API Keys (required for respective providers)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
OPENROUTER_API_KEY=sk-or-...

# Custom API Key Suffixes (for different environments)
ANTHROPIC_API_KEY_DEV=sk-ant-...  # For model: anthropic:claude:dev
OPENAI_API_KEY_PROD=sk-...        # For model: openai:gpt-4:prod

# Behavior Control
MAX_STEPS=1000            # Override max steps (default: 1000)

# Development/Testing
NODE_TLS_REJECT_UNAUTHORIZED=0    # Allow self-signed certs (localhost only)

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 auth login [provider]    # Authenticate with a provider
agentuse auth logout [provider]   # Remove stored credentials
agentuse auth list                # Show authentication status
agentuse auth help                # Show detailed auth help
agentuse --version                # Show version
agentuse --help                   # Show help

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

Or set your API key:
  export ANTHROPIC_API_KEY='your-key-here'

For more options: agentuse auth --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

Guides

Reference

CLI Commands

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 auth

Subcommands

auth logout

auth list

auth help

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

Getting Started

Guides

Reference

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

​Subcommands

​auth login

​auth logout

​auth list

​auth help

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

Subcommands

auth login

auth logout

auth list

auth help

agentuse help

Syntax

Examples

Global Options

Environment Variables

Exit Codes

Available Commands

Advanced Usage

Piping

Shell Integration

Batch Processing

Troubleshooting

Next Steps