Workspace CLI

Docs / Reference / Workspace CLI

Workspace CLI

agentrq-ws is everything an agent can do in a workspace, from a shell, without spending an agent's tokens to do it. It reads the .mcp.json in the current directory — the same file the agent working there uses — so inside a workspace checkout there is nothing to configure.

Why it exists, and what the base64 round-trip costs an agent without it, is the subject of MCP Attachment Base64 Cost: Why AgentRQ Has a Workspace CLI.

Install

Nothing to install: npx fetches it on demand, and it has no runtime dependencies. Node 20.6 or newer.

Run it once, or keep it

npx @agentrq/agentrq-ws@latest help

npm install -g @agentrq/agentrq-ws
agentrq-ws help

The package is @agentrq/agentrq-ws on npm, Apache-2.0, and its source is in cli/agentrq-ws.

Inside a workspace checkout

cd ~/code/my-workspace
agentrq-ws workspace

Commands

Fourteen commands over the workspace's eleven MCP tools. Every command takes --help, and so does every family: agentrq-ws task --help lists the task commands, agentrq-ws attachment get -h explains that one.

Command	What it does	Tool
`workspace`	Show the workspace title and mission	getWorkspace
`task get <taskId>`	Fetch a task, with `--conversation` for its history	getTask
`task next`	Take the next not-started task — this dequeues the queue	getTask
`task create <title>`	Create a task	createTask
`task status <taskId> <status>`	Set a task's status	updateTaskStatus
`reply <taskId> <text>`	Send a message to a task	reply
`attachment get <id>`	Download an attachment to a file	downloadAttachment
`memory load [name]`	Read a workspace memory, the index by default	loadMemory
`memory save [name]`	Replace a workspace memory	saveMemory
`memory delete [name]`	Delete a workspace memory	deleteMemory
`event publish <name>`	Publish a named event	publishEvent
`ask <taskId> <message>`	Ask the human a question and wait	elicit
`tools`	List the tools this workspace server offers	tools/list
`call <tool>`	Call any tool directly with JSON arguments	any

task next Claims Work

It is a separate verb rather than a bare task get on purpose: it mutates the queue, and a command that silently claims work is a bad surprise.

Statuses accepted by task status: notstarted, ongoing, completed, rejected, cron, blocked.

Attachments Never Become Your Problem

The underlying tools speak base64 in both directions. This CLI does not. Uploading takes a path — the filename, media type and encoding are worked out for you, in this process rather than in an agent's context.

Uploading

agentrq-ws reply 0isnjTCkpW5 "Build is green — log attached" --attach ./run.log
agentrq-ws task create "Review the design" --body @brief.md --attach ./mock.png

Downloading writes a file and prints where it went. With no --out it lands in the OS temp directory; --out takes a directory (keeping the attachment's own name) or a full path (renaming it).

Downloading

$ agentrq-ws attachment get 0isp9dJxr85 --task 0isnjTCkpW5
/tmp/agentrq-ws-help.txt

$ agentrq-ws attachment get 0isp9dJxr85 --task 0isnjTCkpW5 --out ~/Downloads
$ agentrq-ws attachment get 0isp9dJxr85 --task 0isnjTCkpW5 --out ./report.pdf

Why --task Is Required

The download tool returns bytes and no filename. The task is where the name lives, so the CLI reads the task first and your file arrives called what a human called it. A task whose text does not mention the id still downloads — under the id as a name — because refusing would be worse than a plainly-named file.

Long Text

Anywhere prose is expected — --body, --content, --payload, and a reply's text — @path reads a file and - reads stdin.

Files and pipes

agentrq-ws task create "Post-mortem" --body @notes.md
git log --oneline -20 | agentrq-ws reply 0isnjTCkpW5 -
agentrq-ws memory save release-notes.md --content @CHANGELOG.md

Asking the Human Something

Two shapes: a form, or a link to go and do something. Both block until the human answers or the timeout elapses — --timeout seconds, one hour by default and at most. The mode is inferred from which of the two you gave.

ask

agentrq-ws ask 0isnjTCkpW5 "Which branch should I release from?" \
  --field branch:string:"Branch name" --field sign:boolean:"Sign the tag?"

agentrq-ws ask 0isnjTCkpW5 "Approve the deploy, then confirm" --url https://example.com/approve

--field name:type:description builds the form schema; types are string, number, integer and boolean, because the protocol restricts an elicitation to a flat object of primitives. --schema @file covers anything the shorthand cannot say.

Choosing a Server

The nearest .mcp.json at or above the working directory is used — the CLI walks up the way git looks for a repository, because an agent's working directory is often a subdirectory of the one holding the config. When that file defines several servers, name one.

Picking one of several

agentrq-ws workspace --server agentrq-workspace
agentrq-ws workspace --config ../other/.mcp.json

Variable	Effect
`AGENTRQ_WS_URL`	Use this server URL and ignore `.mcp.json` entirely
`AGENTRQ_WS_SERVER`	Which server in `.mcp.json` to use

An ambiguous config is an error that lists the names rather than a guess: connecting to the wrong server would act on the wrong workspace.

Output and Exit Codes

Commands print the server's text. --json prints the raw result instead, for piping into jq.

Piping

agentrq-ws tools --json | jq -r '.[].name'

Failures print one line and exit non-zero. A stack trace means a bug in the CLI, not a mistake in the command. Piping into a reader that stops early, such as | head, exits zero — closing the pipe is the reader's decision.

Why It Exists

The base64 round-trip, and what it costs an agent

Workspace MCP

The tools underneath every command here

Workspaces

Where the .mcp.json and its token come from