CLI Commands

agentuse run <agent-file> [prompt...] [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

# 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

provider:model[:env]

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

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

# 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 serve [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>  Working directory for agent resolution
-d, --debug             Enable debug mode
--no-auth               Disable API key requirement for exposed hosts (dangerous)

# Set API key for authentication
export AGENTUSE_API_KEY="your-secret-key"

# Start server on all interfaces
agentuse serve --host 0.0.0.0

curl -X POST http://server:12233/run \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"agent": "my-agent.agentuse"}'

{
  "agent": "path/to/agent.agentuse",
  "prompt": "Optional additional prompt",
  "model": "anthropic:claude-sonnet-4-5",
  "timeout": 300,
  "maxSteps": 100
}

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

{
  "success": false,
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent file not found: my-agent.agentuse"
  }
}

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"}'

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

# 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

# Use specific project directory
agentuse serve -C /path/to/project

# Start with debug logging
agentuse serve --debug

# 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"}'

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

agentuse auth login [provider]

# Interactive login (shows provider selection)
agentuse auth login

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

agentuse auth logout [provider]

# Logout from all providers
agentuse auth logout

# Logout from specific provider
agentuse auth logout openai

agentuse auth list
# or
agentuse auth ls

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

Stored credentials:
  🔑 anthropic (oauth) → Use as: anthropic:claude-sonnet-4-5
  🎫 openai (api) → Use as: openai:gpt-5.2
  🎫 openrouter (api) → Use as: openrouter:z-ai/glm-4.7

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

Model usage examples:
  agentuse run agent.agentuse --model anthropic:claude-sonnet-4-5
  agentuse run agent.agentuse --model openai:gpt-5.2
  agentuse run agent.agentuse --model openrouter:z-ai/glm-4.7

agentuse auth help

agentuse skills [options]

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

# List all available skills
agentuse skills

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

Found 2 skill(s):

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

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

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

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

# General help
agentuse --help

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

# Show help when no arguments provided
agentuse

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

agentuse run <file> [prompt...]   # Run an agent with optional prompt
agentuse serve [options]          # Start HTTP server to run agents via API
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 skills [options]         # List available skills
agentuse --version                # Show version
agentuse --help                   # Show help

# 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

# Bash function
agent() {
  agentuse run "$1.agentuse" "${@:2}"
}

# Usage
agent translator "Hello world"

# 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 {}