VirtuAI CLI

The VirtuAI CLI (virtuai) connects a terminal to your workspace. With it you can:

• chat with an agent in an interactive terminal app (virtuai chat)
• send one-off prompts from scripts and pipes (virtuai ask)
• run a local runner, so deep agents run their shell commands and file edits on your machine instead of a cloud sandbox (virtuai run)

The agent itself runs on VirtuAI. Only its command and file tools run on your machine.

Before you start

• Python 3.11 or newer
• A VirtuAI account in the workspace
• An agent with CLI turned on in its Channels card. It’s on by default, and the card reads Accessible via terminal.

Install

pipx install virtuai-cli

pip install virtuai-cli works too. pipx keeps the CLI in its own environment and puts virtuai on your PATH.

Pair this machine

Pairing links the CLI to one workspace.

1. In VirtuAI, open Settings and find Local CLI. Select Pair local CLI.

2. Copy the command it shows. The code expires in 10 minutes and works once.

3. Run it in your terminal, adding your VirtuAI address:

   virtuai pair <CODE> --server https://<your-virtuai-host>

   The CLI prints the workspace it paired with and remembers the server.

The CLI keeps its token in your system keychain.

Caution

A workspace has one CLI pairing at a time. Pairing another machine, or selecting New pairing code, disconnects the previous one.

To chat as yourself, so conversations are tied to your own user, also run virtuai login. It opens a browser page that gives you a token to paste. The token lasts 90 days.

Chat

virtuai chat
virtuai chat --agent <agent-id-or-name>

Pick an agent, type, and watch the answer stream in. The agent’s tool calls show up as they run.

Command	What it does
/help	Lists the commands
/new or /clear	Starts a new conversation
/history	Lists your recent conversations with this agent
/load <id>	Reopens a past conversation
/agents	Lists the workspace’s agents
/agent <name>	Switches agent and starts a new conversation
/plan	Switches to the built-in Plan agent, which explores and designs but doesn’t change anything
/models and /model <id>	Lists the agent’s models, or switches model
/exit or /quit	Closes the app

Keys: Esc cancels the reply in progress, Ctrl+L starts a new conversation, Ctrl+C quits.

Use it in scripts

virtuai ask sends one message, prints the answer and exits. It reads standard input when you pipe into it.

virtuai ask "summarize the changes in this branch"
git diff | virtuai ask "what does this change?"
ANSWER=$(virtuai ask -q "give me a one-line summary of README.md")
virtuai ask --json "find any bugs" > events.jsonl

Option	What it does
--agent <id-or-name>	Picks the agent
--model <id>	Overrides the agent’s default model
--session <id>	Continues an earlier conversation
--print-session	Prints the conversation ID when done, for use with --session
-q, --quiet	Prints only the final answer
--json	Prints every event as one JSON line
--no-tools	Starts faster without local tools. Fails if the agent tries to use one.
--workdir <path>	The folder the agent may work in. Default: the current folder.

By default, the answer goes to standard output and tool progress to standard error, so > out.txt captures only the answer. Exit codes: 0 success, 1 error during the reply, 2 bad arguments or agent not found.

Run the local runner

virtuai run

While it runs, deep agents in the workspace run their commands and file edits on this machine, in ~/virtuai unless you pass --workdir. This applies to every channel, not only the terminal. Settings > Local CLI shows the runner as Connected, with its host and folder.

If a message arrives while the runner is reconnecting, VirtuAI waits briefly for it. If it doesn’t come back, the person is told the environment isn’t responding.

Use --isolate-sessions when one runner serves several people. Each conversation then gets its own folder.

Other commands

Command	What it does
virtuai status	Shows the server, workspace, pairing and connection
virtuai logs	Shows recent commands the agent ran on this machine
virtuai unpair	Removes this machine’s pairing
virtuai config get / set	Reads or changes local options, such as server_url
virtuai opencode	Connects the OpenCode editor. See OpenCode.

Security

The agent acts as you

Commands run as your user account, with your permissions. There is no sandbox. Treat the runner like a shell session you don’t fully trust.

What the CLI does to limit mistakes:

• File tools can’t read or write outside the working folder.
• cd can’t leave the working folder in bash.
• Commands such as sudo, rm -rf / and disk formatting are blocked.
• Every command and its exit code is logged to ~/.virtuai/audit.log.
• The agent only has access while virtuai chat, virtuai ask or virtuai run is running.

What it doesn’t stop:

• Shell commands can use absolute paths, so they can read, change or delete anything your account can.
• Other interpreters, such as python or node, can leave the working folder.
• The block list is a pattern match and can be worked around.
• Network access isn’t restricted.

For real isolation, run the CLI in a container with only your project folder mounted:

docker run --rm -it -v "$PWD:/work" -w /work python:3.12 \
  bash -c "pip install virtuai-cli && virtuai pair <CODE> --server https://<your-virtuai-host> && virtuai chat"

Run models on your machine with Ollama

An agent can run its model on your machine through Ollama. The rest of the agent, including its tools, knowledge bases and history, stays on VirtuAI.

1. Install the CLI with local support:

   pipx install 'virtuai-cli[local]'

2. Install Ollama, start it, and pull a model that supports tool calling:

   ollama pull qwen3:8b

3. Edit the agent. In AI Model Configuration, set Provider to Local (Ollama), enter the model tag you pulled, and choose a cloud fallback model.

4. Use the agent from virtuai chat, virtuai ask or virtuai run.

The CLI reaches Ollama at http://localhost:11434. Set OLLAMA_BASE_URL to change it. If the CLI isn’t connected, Ollama isn’t running, or the model isn’t pulled, the agent uses its cloud fallback model and says so.

Troubleshooting

“Invalid or expired pairing code” : The code is older than 10 minutes or was already used. Generate a new one.

401 errors after it worked before : Someone paired another machine to the workspace. Pair this one again.

The agent isn’t in the list : Check that CLI is on in the agent’s Channels card, and that virtuai status shows the right server and workspace.

The agent says the environment isn’t responding : The runner stopped. Start virtuai run again.