CLI de VirtuAI

La CLI de VirtuAI (virtuai) conecta una terminal con tu espacio de trabajo. Con ella puedes hacer lo siguiente:

• chatear con un agente en una app de terminal interactiva (virtuai chat)
• enviar prompts puntuales desde scripts y canalizaciones (virtuai ask)
• ejecutar un runner local para que los agentes Deep ejecuten sus comandos de shell y ediciones de archivos en tu máquina en lugar de en una zona de pruebas en la nube (virtuai run)

El agente se ejecuta en VirtuAI. Solo sus herramientas de comandos y de archivos se ejecutan en tu máquina.

Antes de comenzar

• Python 3.11 o una versión posterior
• Una cuenta de VirtuAI en el espacio de trabajo
• Un agente con CLI activado en su tarjeta Channels. Está activado de forma predeterminada, y la tarjeta muestra Accessible via terminal.

Instala la CLI

pipx install virtuai-cli

pip install virtuai-cli también funciona. pipx mantiene la CLI en su propio entorno y agrega virtuai a tu PATH.

Vincula esta máquina

La vinculación conecta la CLI con un espacio de trabajo.

1. En VirtuAI, abre Settings y busca Local CLI. Selecciona Pair local CLI.

2. Copia el comando que se muestra. El código vence en 10 minutos y funciona una sola vez.

3. Ejecútalo en tu terminal y agrega tu dirección de VirtuAI:

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

   La CLI muestra el espacio de trabajo con el que se vinculó y recuerda el servidor.

La CLI guarda su token en el llavero del sistema.

Precaución

Un espacio de trabajo tiene una sola vinculación de CLI a la vez. Si vinculas otra máquina o seleccionas New pairing code, se desconecta la anterior.

Para chatear con tu propia identidad, de modo que las conversaciones queden asociadas a tu usuario, ejecuta también virtuai login. Abre una página del navegador que te da un token para pegar. El token dura 90 días.

Chatea

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

Elige un agente, escribe y observa cómo se transmite la respuesta. Las llamadas a herramientas del agente aparecen a medida que se ejecutan.

Comando	Qué hace
/help	Muestra los comandos
/new o /clear	Inicia una conversación nueva
/history	Muestra tus conversaciones recientes con este agente
/load <id>	Vuelve a abrir una conversación anterior
/agents	Muestra los agentes del espacio de trabajo
/agent <name>	Cambia de agente e inicia una conversación nueva
/plan	Cambia al agente Plan integrado, que explora y diseña, pero no cambia nada
/models y /model <id>	Muestra los modelos del agente o cambia de modelo
/exit o /quit	Cierra la app

Teclas: Esc cancela la respuesta en curso, Ctrl+L inicia una conversación nueva y Ctrl+C sale.

Úsala en scripts

virtuai ask envía un mensaje, imprime la respuesta y sale. Lee la entrada estándar cuando le canalizas datos.

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

Opción	Qué hace
--agent <id-or-name>	Elige el agente
--model <id>	Anula el modelo predeterminado del agente
--session <id>	Continúa una conversación anterior
--print-session	Imprime el ID de la conversación al terminar, para usarlo con --session
-q, --quiet	Imprime solo la respuesta final
--json	Imprime cada evento como una línea JSON
--no-tools	Se inicia más rápido sin herramientas locales. Falla si el agente intenta usar una.
--workdir <path>	La carpeta en la que puede trabajar el agente. Valor predeterminado: la carpeta actual.

De forma predeterminada, la respuesta va a la salida estándar y el progreso de las herramientas va a la salida de error estándar, así que > out.txt captura solo la respuesta. Códigos de salida: 0 éxito, 1 error durante la respuesta, 2 argumentos incorrectos o agente no encontrado.

Ejecuta el runner local

virtuai run

Mientras se ejecuta, los agentes Deep del espacio de trabajo ejecutan sus comandos y ediciones de archivos en esta máquina, en ~/virtuai, a menos que pases --workdir. Esto se aplica a todos los canales, no solo a la terminal. Settings > Local CLI muestra el runner como Connected, con su host y su carpeta.

Si llega un mensaje mientras el runner se está reconectando, VirtuAI lo espera un momento. Si no vuelve, se le informa a la persona que el entorno no responde.

Usa --isolate-sessions cuando un runner atienda a varias personas. Así, cada conversación tiene su propia carpeta.

Otros comandos

Comando	Qué hace
virtuai status	Muestra el servidor, el espacio de trabajo, la vinculación y la conexión
virtuai logs	Muestra los comandos recientes que el agente ejecutó en esta máquina
virtuai unpair	Quita la vinculación de esta máquina
virtuai config get / set	Lee o cambia opciones locales, como server_url
virtuai opencode	Conecta el editor OpenCode. Consulta OpenCode.

Seguridad

El agente actúa como tú

Los comandos se ejecutan con tu cuenta de usuario y con tus permisos. No hay zona de pruebas. Trata el runner como una sesión de shell en la que no confías por completo.

Lo que hace la CLI para limitar los errores:

• Las herramientas de archivos no pueden leer ni escribir fuera de la carpeta de trabajo.
• cd no puede salir de la carpeta de trabajo en bash.
• Se bloquean comandos como sudo, rm -rf / y el formateo de discos.
• Cada comando y su código de salida se registran en ~/.virtuai/audit.log.
• El agente solo tiene acceso mientras se ejecuta virtuai chat, virtuai ask o virtuai run.

Lo que no impide:

• Los comandos de shell pueden usar rutas absolutas, así que pueden leer, cambiar o borrar cualquier cosa a la que tenga acceso tu cuenta.
• Otros intérpretes, como python o node, pueden salir de la carpeta de trabajo.
• La lista de bloqueo es una coincidencia de patrones y se puede eludir.
• El acceso a la red no está restringido.

Para lograr un aislamiento real, ejecuta la CLI en un contenedor que solo tenga montada la carpeta de tu proyecto:

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"

Ejecuta modelos en tu máquina con Ollama

Un agente puede ejecutar su modelo en tu máquina a través de Ollama. El resto del agente, incluidas sus herramientas, sus bases de conocimiento y su historial, permanece en VirtuAI.

1. Instala la CLI con compatibilidad local:

   pipx install 'virtuai-cli[local]'

2. Instala Ollama, inícialo y descarga un modelo que admita llamadas a herramientas:

   ollama pull qwen3:8b

3. Edita el agente. En AI Model Configuration, configura Provider como Local (Ollama), ingresa la etiqueta del modelo que descargaste y elige un modelo de respaldo en la nube.

4. Usa el agente desde virtuai chat, virtuai ask o virtuai run.

La CLI se conecta a Ollama en http://localhost:11434. Configura OLLAMA_BASE_URL para cambiarlo. Si la CLI no está conectada, Ollama no se está ejecutando o el modelo no se descargó, el agente usa su modelo de respaldo en la nube y lo indica.

Solución de problemas

“Invalid or expired pairing code” : El código tiene más de 10 minutos o ya se usó. Genera uno nuevo.

Errores 401 después de que funcionó antes : Alguien vinculó otra máquina al espacio de trabajo. Vuelve a vincular esta.

El agente no aparece en la lista : Verifica que CLI esté activado en la tarjeta Channels del agente y que virtuai status muestre el servidor y el espacio de trabajo correctos.

El agente indica que el entorno no responde : El runner se detuvo. Vuelve a iniciar virtuai run.