Skip to main content
The agent command provides direct access to Weaver’s AI agent through the command line, supporting both single-message and interactive modes.

​
Usage

weaver agent [options]

​
Modes

​
Single Message Mode

Send a single message and receive a response: 
weaver agent -m "What's the weather like?"
Output: 
🔍 Debug mode enabled (if -d flag used)
🕸️ Based on your location, the current weather is...

​
Interactive Mode

Start a conversational session: 
weaver agent
Output: 
🕸️ Interactive mode (Ctrl+C to exit)

🕸️ You: Hello!

🕸️ Hello! How can I assist you today?

🕸️ You:

​
Options

​
-m, --message
string
Single message to send to the agentWhen provided, agent runs in single-message mode and exits after response.
weaver agent -m "Summarize the latest news"
​
-s, --session
string
default:"cli:default"
Session key for conversation historyUse different session keys to maintain separate conversation contexts.
weaver agent -s "project-alpha" -m "What did we discuss?"
​
-d, --debug
flag
Enable debug mode with verbose loggingDisplays detailed log output to help troubleshoot issues.
weaver agent --debug -m "Test message"
Output includes:
  • Tool loading details
  • Skill availability
  • Provider API calls

​
Interactive Mode Features

​
Command History

Interactive mode uses readline with persistent history:
  • Location: /tmp/.weaver_history
  • Limit: 100 entries
  • Navigation: Up/Down arrows

​
Exit Commands

Multiple ways to exit interactive mode: 
🕸️ You: exit
Goodbye!

🕸️ You: quit
Goodbye!

🕸️ You: ^C
Goodbye!

​
Fallback Mode

If readline initialization fails, agent falls back to simple input mode: 
Error initializing readline: ...
Falling back to simple input mode...
🕸️ You:

​
Startup Information

Agent displays initialization details: 
🕸️ Agent initialized
  - Tools: 12 loaded
  - Skills: 4/6 available

​
Examples

$ weaver agent -m "What's 15% of 250?"

🕸️ 15% of 250 is 37.5.

​
Session Management

Sessions persist conversation history across commands: 
# First message in session
weaver agent -s "project-x" -m "We're building a chatbot"

# Later message in same session (remembers context)
weaver agent -s "project-x" -m "What are we building?"
# Response: "You mentioned you're building a chatbot."
Default session key: cli:default

​
Exit Codes

CodeReason
0Success - message processed
1Config loading failed
1Provider creation failed
1Message processing error (in single-message mode)

​
Error Handling

​
Configuration Errors

Error loading config: open ~/.weaver/config.json: no such file or directory
Run weaver onboard first.

​
Provider Errors

Error creating provider: API key not configured
Add API key to ~/.weaver/config.json: 
"openrouter": {
  "api_key": "sk-or-..."
}

​
Processing Errors (Interactive Mode)

🕸️ You: What's the weather?

Error: API rate limit exceeded

🕸️ You:
Interactive mode continues after errors.

​
Processing Errors (Message Mode)

$ weaver agent -m "Test"
Error: API rate limit exceeded
$ echo $?
1
Message mode exits with code 1 on errors.

​
Performance Notes

  • Startup time: ~1-2 seconds (loads tools and skills)
  • Response time: Varies by model and complexity
  • Memory usage: ~50-100 MB baseline

Build docs developers (and LLMs) love

Get started for freeTalk to us