Skip to content

cli.md

Latest commit

 

History

History
411 lines (301 loc) · 14 KB

cli.md

File metadata and controls

411 lines (301 loc) · 14 KB
Raw

qcr CLI Reference

Synopsis

qcr [OPTIONS] [PROMPT]
qcr [OPTIONS] <SUBCOMMAND>

Modes

Mode Trigger Description
Interactive TUI default (stdin is TTY) Full terminal UI with conversation history
Headless --headless or stdin is not TTY No TUI; stream output to stdout
Print --print Single prompt, print response, exit 0
ACP --acp ndjson JSON-RPC 2.0 stdio transport for IDE integration
Serve qcr serve HTTP server exposing A2A and AG-UI protocol endpoints

Options

Core

Flag Short Env Default Description
--model <MODEL> -m QCR_MODEL qwen3-coder LLM model ID
--provider <PROVIDER> QCR_PROVIDER dashscope Provider name (openai, anthropic, gemini, dashscope, groq, openrouter)
--print -p false Print mode: run one turn, output to stdout, exit
--headless false Headless mode: no TUI, plain text streaming
--acp false ACP mode: ndjson JSON-RPC 2.0 over stdio for IDE integration
--config <PATH> -c none Path to project config directory
--system-prompt <TEXT> none Override system prompt

Approval

Flag Env Values Default Description
--approval-mode <MODE> QCR_APPROVAL_MODE always, never, suggest suggest Tool execution approval policy
  • always — deny all tool calls (safe sandbox mode)
  • never — approve all tool calls automatically
  • suggest — prompt for approval on write/execute tools (TUI only)

Session

Flag Description
--resume <SESSION_ID> Resume a saved session by ID

Output

Flag Short Values Default Description
--output-format <FORMAT> -f text, json, jsonl text Output format for headless/print mode
  • text — plain streaming text (default)
  • json — single JSON object at end: {"model", "response", "turns", "usage"}
  • jsonl — one JSON object per event: {"type":"text_delta","delta":"..."} etc.

Planning

Flag Short Description
--plan-mode -P Start in plan mode (LLM describes actions without executing tools)

Limits

Flag Env Default Description
--max-turns <N> QCR_MAX_TURNS 20 Maximum agentic loop turns before stopping

Debug

Flag Short Description
--verbose -v Enable verbose/debug logging (RUST_LOG=debug)

Subcommands

qcr info

Print version and build info.

qcr info

Output:

qcr 0.1.13 (qcr-rust)
  core: qcr-core v0.1.13

qcr config

Manage configuration.

Subcommand Description
qcr config show Print merged config as JSON
qcr config get <KEY> Get a single config value
qcr config set <KEY> <VALUE> Set a config value in settings.json
qcr config edit Open settings.json in $EDITOR
qcr config path Print path to global settings.json

qcr session

Manage saved sessions.

Subcommand Description
qcr session list List all saved sessions
qcr session resume <ID> Resume a session by ID
qcr session delete <ID> Delete a session
qcr session clear Delete all sessions

qcr mcp

Manage MCP (Model Context Protocol) servers.

Subcommand Description
qcr mcp list List configured MCP servers

qcr plugin

Manage plugins.

Subcommand Description
qcr plugin list List installed plugins (global and project)
qcr plugin install <SOURCE> Install a plugin from a local path or git URL
qcr plugin remove <NAME> Remove an installed plugin

Plugins are loaded from ~/.qcr/plugins/ (global) and .qcr/plugins/ (project-local). See docs/plugins.md for the plugin format and directory structure.

qcr serve

Start an HTTP server exposing A2A (Agent-to-Agent) and AG-UI (Agent-User Interface) protocol endpoints.

qcr serve [OPTIONS]
Flag Default Description
--host <ADDR> 127.0.0.1 Bind address
--port <PORT> / -P 4200 Port number

Endpoints served:

Path Protocol Description
/.well-known/agent.json A2A Agent card (GET) — agent identity, capabilities, skills
/a2a A2A JSON-RPC 2.0 endpoint (POST) — message/send, message/stream, tasks/get, tasks/cancel
/ag-ui/run AG-UI SSE run endpoint (POST) — accepts RunAgentInput, streams AG-UI events
/health — Health check (GET) — returns "ok"

Examples:

# Start on default port
qcr serve

# Custom port and bind to all interfaces
qcr serve --host 0.0.0.0 --port 8080

# Test the agent card
curl http://localhost:4200/.well-known/agent.json

# Send an A2A task
curl -X POST http://localhost:4200/a2a \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"message/send","params":{"message":{"role":"user","parts":[{"type":"text","text":"Hello"}]}}}'

# Stream AG-UI events
curl -X POST http://localhost:4200/ag-ui/run \
  -H "Content-Type: application/json" \
  -d '{"threadId":"t1","runId":"r1","messages":[{"id":"m1","role":"user","content":"Hello"}],"state":{},"tools":[],"context":[]}'

See also: A2A Protocol and AG-UI Protocol sections below.

qcr chat <MESSAGE>

Alias: start a conversation with an initial message (equivalent to qcr "<MESSAGE>").

Slash Commands (TUI only)

Type these in the input box during an interactive session:

Command Description
/help Show available slash commands
/auto (alias /ac) Toggle auto-continue mode on/off — agent re-spawns automatically after each turn while pending tasks remain
/clear Clear conversation history
/model <name> Switch model mid-session
/plan Toggle plan mode on/off
/compact Compress conversation history to save context
/undo Revert the last file edit (pops the per-file undo stack)
/spec <feature> Start a spec workflow — creates .kiro/specs/<feature>/ with requirements, design, and tasks files
/resume <id> Load a saved session
/sessions List saved sessions
/title <text> Set session title
/loop [interval] <prompt> Schedule a recurring prompt. Interval optional (default 10m). See scheduled-tasks.md

Plugin Commands

Plugins can contribute additional slash commands. Any /command not matched by the built-in list above is looked up in the plugin command registry.

Behaviour Description
Exact match Command content is injected as a user message and the agent runs a turn
Ambiguous match Error shown listing all matching plugin:command names — use the namespaced form
Not found Error shown: unknown command: /name

Use the namespaced form to resolve ambiguity when two plugins define the same short name:

/my-plugin:deploy
/other-plugin:deploy

See docs/plugins.md for how to install plugins and write commands.

Key Bindings (TUI)

Key Action
Enter Send message
Ctrl+C Cancel current agent turn (or quit if idle). Also disables auto-continue if active.
Ctrl+D Quit
Ctrl+N Toggle auto-continue mode on/off (same as /auto)
Ctrl+A Cycle approval mode: auto-approve ↔ interactive
Ctrl+H Cycle thinking display: Preview → Full → Hidden
Ctrl+T Toggle task panel
Ctrl+L Clear conversation display (keeps welcome message)
Up / Down Scroll conversation history
Left / Right Move cursor in input
Ctrl+U Clear input line

Auto-Continue Mode

Auto-continue mode lets the agent keep working through a task list without requiring you to manually re-submit after each turn.

How it works:

  1. Enable it with /auto (or Ctrl+N) — a bright-green AUTO badge appears in the status bar.
  2. When the agent finishes a turn (Done or MaxTurnsReached), qcr checks the task panel for pending ([ ]) or in-progress ([→]) items.
  3. If any remain, qcr automatically injects a "Continue working on the remaining tasks" message and spawns the next agent turn — no keypress needed.
  4. The cycle continues until all tasks are marked done, the agent produces a turn-ending response with no pending tasks, or you press Ctrl+C (which also turns auto-continue off).

Best practice: Use TodoWrite at the start of a complex job to lay out your task list. Auto-continue then drives the agent through the list turn by turn.

Spec-driven workflow interaction: When auto-continue is on, the spec-driven-development skill runs without pausing at phase boundaries — the agent completes Requirements → Design → Tasks → Execution uninterrupted. When auto-continue is off, the skill pauses after each phase (requirements, design, tasks) and after each individual execution task, waiting for your explicit approval before proceeding. Toggle /auto before invoking /spec to control this behaviour.

Stopping: Press Ctrl+C at any point. This cancels the running turn and disables auto-continue in one action (message: [cancelled] [auto-continue: off]). You can also toggle it off between turns with /auto or Ctrl+N.

Environment Variables

Variable Description
QCR_MODEL Default model ID
QCR_PROVIDER Default provider
QCR_APPROVAL_MODE Approval policy: always, never, suggest
QCR_MAX_TURNS Max agent loop turns
QCR_MAX_TOKENS Max completion tokens
QCR_TEMPERATURE Sampling temperature (0.0–2.0)
OPENAI_API_KEY API key for OpenAI-compatible providers
OPENAI_API_BASE Override base URL for OpenAI provider (e.g. proxy)
QCR_API_BASE Same as OPENAI_API_BASE (alias)
DASHSCOPE_API_KEY API key for DashScope / Alibaba Cloud
ANTHROPIC_API_KEY API key for Anthropic
OPENROUTER_API_KEY API key for OpenRouter
QCR_DISABLE_CRON Set to 1 to disable the session-scoped cron scheduler
RUST_LOG Log level: error, warn, info, debug, trace
EDITOR Editor for qcr config edit

Examples

Single-turn print mode

qcr --print "Explain the borrow checker in Rust"

Pipe input

cat main.rs | qcr --print "Review this code for bugs"

JSON output for scripting

qcr --print --output-format json "What is 2+2?" | jq .response

Use a specific model and provider

qcr --provider openai --model gpt-4o "Refactor this function"

Use a proxy or local LLM

OPENAI_API_BASE=http://localhost:11434/v1 OPENAI_API_KEY=ollama \
  qcr --provider openai --model llama3.2 --print "Hello"

Auto-approve all tools (non-interactive CI)

qcr --approval-mode never --print "Create a hello.txt file with Hello World"

Plan mode (describe without executing)

qcr --plan-mode --print "Refactor the auth module"

Resume a session

qcr session list
qcr --resume <SESSION_ID>

Headless streaming in CI

qcr --headless --approval-mode never "Run the tests and fix any failures"

Exit Codes

Code Meaning
0 Success
1 Agent error (API error, tool failure, etc.)
2 Invalid arguments (clap parse error)

A2A Protocol

Qwen Code Rust implements the Google A2A (Agent-to-Agent) protocol, enabling interoperability with other A2A-compliant agents. When running qcr serve, the following A2A capabilities are available:

Agent Card (GET /.well-known/agent.json):

  • Advertises agent name, description, version, capabilities (streaming), and skills
  • Skills are derived from the tool registry (first 20 tools)
  • Customizable via a2a config section

JSON-RPC Methods (POST /a2a):

Method Description
message/send Send a message, wait for complete task result
message/stream Send a message, receive SSE stream of task updates
tasks/get Retrieve a task by ID (with optional history limit)
tasks/cancel Cancel a running task

Task States: submitted → working → completed / failed / canceled

SSE Stream Events (for message/stream):

  • statusUpdate — task state transitions with timestamps
  • artifactUpdate — incremental output artifacts (text chunks, tool results)

AG-UI Protocol

Qwen Code Rust implements the CopilotKit AG-UI protocol, enabling frontend applications to drive agent sessions and receive real-time streaming events.

Run Endpoint (POST /ag-ui/run):

Accepts a RunAgentInput payload:

{
  "threadId": "conversation-id",
  "runId": "unique-run-id",
  "messages": [{"id": "m1", "role": "user", "content": "Hello"}],
  "state": {},
  "tools": [],
  "context": []
}

Returns an SSE event stream with typed events:

Event Description
RUN_STARTED Agent run began
TEXT_MESSAGE_START / CONTENT / END Streaming assistant text
TOOL_CALL_START / ARGS / END / RESULT Tool call lifecycle
STEP_STARTED / STEP_FINISHED Logical execution steps
REASONING_MESSAGE_START / CONTENT / END Chain-of-thought reasoning
STATE_SNAPSHOT Agent state snapshot
RUN_FINISHED Agent run completed
RUN_ERROR Agent run failed

Protocol Stack

Frontend App  <──AG-UI──>  qcr serve  <──A2A──>  Other Agents
                                │
                                └── ContentGenerator + ToolRegistry + AgentLoop
                                         │
                                         └──MCP──>  Tool Servers