Let your AI agent run the Voroa CLI: deploy, check and fix

What this gives you

If your coding agent can run a shell command, it can run Voroa. You say “deploy the API and tell me if it came up”, and the agent runs voroa deploy api --wait --json, reads the answer and reports back. No plugin to install and nothing to configure in the agent - the Voroa CLI is the tool.

The CLI is built so a program can drive it without guessing:

• Every command answers in JSON when you add --json.
• A failure has a code, such as NOT_FOUND or NEEDS_HUMAN, so the agent never has to interpret an English sentence.
• It never waits on a question nobody will answer. With VOROA_NO_INPUT=1, a step that needs a person fails at once and says so.
• One command teaches the agent all of this: voroa agent.

Set it up

1. Install the CLI where the agent runs: npm install -g voroa-cli (Node.js 20 or newer).
2. Create an API token in the dashboard under Settings -> API tokens. Choose the scopes you want the agent to have - read only, or read and act.
3. Give the agent the token as an environment variable, and turn questions off:

VOROA_TOKEN=voroa_cat_...
VOROA_NO_INPUT=1

4. Tell the agent, once: “Run voroa agent and follow it when you work with Voroa.”

That is the whole setup. The agent cannot sign in by itself, and should not: voroa login sends a code to your email. A token is the right credential for it - it is scoped, it expires, and you can revoke it at any moment.

What voroa agent tells it

voroa agent prints a short guide written for a model; voroa agent --json gives the same as data. It covers:

• how to authenticate, and that it must not try to sign in
• to add --json to every command, and to read the exit code rather than the text
• the exit codes: 0 succeeded, 1 failed, 2 still running when the wait ended
• the error codes and what to do about each one
• how to read a service’s health: the verdict field, where sleeping means idle and not broken
• how to look up any command: voroa tools bucket --json lists the matching platform commands with their arguments, and marks which ones change something - so an agent told to only look can tell
• that a secret value never goes on a command line

The error codes

What it cannot do

These limits are enforced by Voroa, not by the agent’s good behaviour:

• Create or delete a service, database or bucket. The agent can only raise a request with voroa propose; you approve it in the dashboard.
• Change your plan or take a payment. It can read invoices and usage, and nothing more.
• Read a secret. Environment variable values and database passwords are never shown, to anyone.

Things worth asking for

• “Deploy web, wait for it, and if it fails read the build log and tell me why.”
• “Which of my services are not running?” (it runs voroa status --all --json)
• “Show me the last 50 log lines of api and look for errors.”
• “Roll web back to the previous version.”
• “Add a scheduled task to worker that runs node cleanup.js every night.”

Related guides

• Voroa CLI overview
• Voroa CLI command reference
• Use Voroa with a coding agent
• Connect an AI client