VirtuAI CLI

Run VirtuAI agents from your terminal — chat interactively in a Claude-Code-style TUI, or pipe them into shell scripts. The agent's bash/file tools run on your machine, so files appear in your filesystem and commands hit your real shell.

Installation

pip install virtuai-cli

Or with pipx (recommended for CLI tools — handles PATH automatically):

pipx install virtuai-cli

For local model inference (running agents against Ollama on your machine — see below), install the local extra:

pip install 'virtuai-cli[local]'      # or: pipx install 'virtuai-cli[local]'

Requires Python 3.11+.

Quick start

1. Pair this machine with a workspace

Open the VirtuAI portal → Settings → CLI → generate a pairing code, then:

virtuai pair <CODE>

The pairing is one-time; the resulting token is stored in your system keychain.

2. Chat with an agent

virtuai chat

Opens an interactive TUI. Pick an agent (skipped if your workspace has only one), type a message, watch the response stream in. The agent's tool calls — bash, file reads, file writes — execute on this machine, in the current directory.

Every workspace includes a built-in Plan agent. Switch to it without leaving the TUI:

/plan

/agent Plan does the same thing. List agents with /agents. Switching starts a new conversation with that agent (history does not carry over). You can also launch Plan directly: virtuai chat --agent Plan. Plan explores the repo and produces a design; it does not implement. Switch back with /agent <name> to execute.

3. Use it from a shell script

virtuai ask "summarize the changes in this branch"

git diff | virtuai ask "what does this change?"

virtuai ask --json "find any bugs" > events.jsonl

ask is non-interactive: it prints the response to stdout, then exits.

Local model inference (Ollama)

Agents can run inference on your own machine via Ollama instead of a cloud provider — useful for cost, data locality, or running open models. Only the model turns are proxied to your machine over the CLI's WebSocket; the agent loop, tools, knowledge bases, and chat history stay on the server.

To use it:

1. Install the CLI with the local extra (pulls langchain-ollama):

   pip install 'virtuai-cli[local]'
   

2. Install Ollama, start it, and pull a tool-capable model:

   ollama serve
   ollama pull qwen3:8b          # instruct/agentic models work best for tool calling
   

3. In the VirtuAI portal, set the agent's Provider to Local (Ollama), enter the model tag you pulled, and pick a cloud fallback model.
4. Connect the CLI (virtuai chat, virtuai ask, or virtuai run) — model turns are now answered by your local Ollama.

The CLI talks to Ollama at http://localhost:11434 by default; override with the OLLAMA_BASE_URL environment variable.

If the CLI isn't connected, Ollama isn't running, or the model isn't pulled, the agent falls back to its configured cloud model and shows a notice. For reliable tool use, prefer instruct/agentic models (e.g. qwen3:*, qwen2.5:*); some code-tuned or non-instruct models emit tool calls as plain text and won't drive the agent's tools.

Commands

Inside virtuai chat

The TUI streams tokens, renders tool calls as live cards (running → complete), tracks the agent's todo list, and shows a randomized "✻ Pondering…" indicator while the agent is composing.

Slash commands (type / to see the filtered list, Tab to autocomplete):

Key bindings:

• Esc — cancel the in-flight response
• Ctrl+L — start a new conversation
• Ctrl+C — quit
• Tab — autocomplete the current /command

virtuai ask for scripting

# Direct prompt
virtuai ask "what's in this folder?"

# Pipe stdin in (concatenated with the argument if both given)
git log --oneline -20 | virtuai ask "summarize these commits"

# Continue a previous session (use --print-session to surface the id)
virtuai ask --session sess-aaa "and apply that fix" --print-session

# Machine-readable: every event as one JSON line
virtuai ask --json "find any bugs" > events.jsonl

# Just the final answer, no streaming (good for capturing into variables)
ANSWER=$(virtuai ask -q "give me the current time")

# Pick a different agent or model
virtuai ask --agent code-review --model claude-opus "review main.py"

# Skip the local runner for a faster startup when no tools are needed
virtuai ask --no-tools "tell me a joke"

Output streams:

• stream (default) — tokens go to stdout, tool indicators to stderr (so > out.txt captures only the answer)
• --quiet / -q — accumulate, print only the final assistant text at the end
• --json — every SSE event as one JSONL line on stdout (parseable)

Exit codes: 0 success · 1 stream error · 2 bad args / agent not found.

Common options

--server <url>       Override the saved server URL
--workdir <path>     Working directory for tool execution (default: current dir)
--agent <id|name>    Pick a specific agent
--model <id>         Override the agent's default model

Security model

Read this section before pointing an agent at anything you care about.

The CLI runs the agent's shell commands as your user account, with your full filesystem permissions. There is no sandbox. The agent can do anything you can do at the shell. The guardrails below are best described as speed bumps, not walls.

What is enforced

• Auth: CLI token is stored in your OS keychain (Keychain on macOS, libsecret on Linux, Credential Manager on Windows). All traffic is TLS (WSS + HTTPS) with the certifi CA bundle.
• File-tool path jail: the deepagents file tools — write_file, edit_file, read_file — route through upload_files/download_files, which reject absolute paths outside the workdir. This part works.
• cd jail in bash: the executor wraps every shell command in a bash subshell with a custom cd function that refuses to leave the workdir. Catches the trivial cd .. case.
• Denylist: a regex match on the command string blocks sudo, rm -rf /, fork bombs, mkfs, dd of=/dev/.... Easy to bypass with aliasing or encoding; mostly there to stop drive-by accidents.
• Audit log: every executed command + exit code goes to ~/.virtuai/audit.log with a timestamp.
• Foreground-only: the agent only has access while virtuai chat, virtuai ask, or virtuai run is running — no background daemon.

What is NOT enforced

• Shell commands can use absolute paths anywhere. The cd jail only intercepts cd. cat /etc/passwd, ls /Users/you/Documents, rm /tmp/whatever — none of these touch cd, so none are blocked. The agent can read, write, and delete anything you can.
• The cd jail itself is bash-only. sh -c '...', python -c "os.chdir('/')", node -e "..." all bypass it.
• Command substitution, eval, env vars, aliases all defeat the denylist. $(echo s)$(echo udo) ... looks nothing like sudo to a regex.
• Network egress is not restricted. The agent can curl/wget anywhere, exfiltrate to any host.

If you need real isolation

The only honest options:

1. Run the CLI inside a container with the workdir bind-mounted and nothing else:

   docker run --rm -it -v "$PWD:/work" -w /work python:3.12 bash -c "pip install virtuai-cli && virtuai pair <code> && virtuai chat"
   

   The container has access only to what you mount.
2. OS-level sandboxing: wrap virtuai run in sandbox-exec on macOS or run inside a landlock/bubblewrap jail on Linux.
3. Switch the agent's backend to the E2B remote sandbox in the portal. The agent then runs against a disposable VM, not your laptop. The CLI runner becomes optional (you'd only need it for "interactive" workflows where local files matter).

Use the CLI runner the same way you'd use a powerful shell session you don't fully trust. Point it at a project directory, never at ~, and don't run unattended on a machine with credentials lying around.

Programmatic use

The async building blocks the TUI is built on are importable directly:

import asyncio
from virtuai_cli import config as cfg
from virtuai_cli.chat.sse import stream_chat

async def main():
    token  = cfg.load_token(cfg._KEYRING_CLI_TOKEN_KEY)
    server = cfg.get_server_url()
    async for event in stream_chat(server, token, "your-agent-id", "Hello"):
        if event.get("type") == "token":
            print(event["content"], end="", flush=True)

asyncio.run(main())

A formal SDK (typed client class, sync wrappers) is on the roadmap.

Links

• Homepage: https://imvirtuai.com
• PyPI: https://pypi.org/project/virtuai-cli/
• Issues / docs: contact your workspace admin