Using io from the terminal
Use @vectara/io to work with io from a shell, provide local files, or run requests from scripts. The CLI uses Vectara's public REST API v2; it has its own approval controls and provisioning requirements.
For the task overview and shared prerequisites, see Getting started with io. You do not need to complete the Console guide first.
Install and start
Node.js 20 or later and network access to your deployment's REST API v2 endpoint are required. Read Scope the CLI API key before supplying credentials to io login.
npm install -g @vectara/io
io login
io
Inside a session, /help lists the slash commands. io --help lists command-line flags.
Press Esc to interrupt a running request when no approval, question, or secret prompt is pending. Ctrl+C also interrupts a running request; press it again when prompted to quit.
Scope the CLI API key
The CLI provisions its own agent, io-assistant-cli, on your tenant rather than modifying Console's io-assistant by default. It stores the supplied API key as an encrypted secret on that CLI agent. The key's permissions determine which operations io can attempt from the terminal.
Scope the key to the work you intend io to perform. Treat the CLI agent as privileged: anyone who can invoke it can ask it to attempt operations allowed by the stored key. See API key management.
Review a proposed change
Review the proposed resource, operation, and body before approving a write. An agent update is a partial change set, not a full replacement; the agent-update table explains preserved fields and removals.
A missing diff is not evidence of a small change. A create has no prior state to compare against, and a proposal may fall back to its raw body if the live resource cannot be read. Inspect the body before approving.
After a successful write, the CLI prints a Console deep link to the affected resource. Use it to inspect the result. See Working effectively with io for shared review guidance.
Answer clarifying questions
Use the arrow keys to choose an option and Enter to submit it. The CLI initially highlights the recommended option when one is present; otherwise it highlights the first option. Press t to type your own answer instead.
Read the highlighted choice before pressing Enter. Unlike Console's recommendation badge, the terminal picker has an active selection.
Print mode (io -p) cannot wait for an interactive answer. If io marks a recommended option, print mode takes it and continues. Otherwise it declines the question with a request for io to proceed using its judgment. Review unattended output with that limitation in mind.
View usage metrics
In an interactive session, a metrics chart offer appears as text with its title, time range, metric names, and a View charts link to Console. The terminal does not display Console's charts inline. See Watch usage and performance for the chart guidance.
Running io unattended
Print mode sends the final answer to standard output and progress to standard error:
io -p "list my corpora"
Proposed writes are rejected without --auto-approve. Provisioning or refreshing the CLI's own agent also counts as a write. If setup is needed, the CLI exits 2; request execution failures exit 1.
A CLI upgrade can change the bundled agent definition. A job that previously ran can therefore need provisioning after an upgrade. Run io bootstrap to prepare the CLI agent, or deliberately approve provisioning in the job.
--auto-approve also approves provisioning. If the target key belongs to an agent that is not CLI-provisioned io, provisioning can overwrite its definition rather than stop. This includes Console's io-assistant when explicitly targeted. Choose --agent-key deliberately and do not treat the flag as approval for only the final task.
Working with local files
/read uploads a local file into the session; /paste uploads a clipboard screenshot. These inputs let you ask io to work from material such as a PDF or an interface image.
Generated files use the workspace directory selected by --workspace or IO_WORKDIR, falling back to the profile's work directory and then the current directory. Review and version generated files as you would other source files.
io's image-reading limit is 2 MB. On macOS, /paste shrinks oversized screenshots and stops if they still exceed the limit. On other platforms it asks you to resize them first. /read uploads the file regardless and warns that io may fail to view it. A successful upload does not establish that the image can be read.
Design a web app
io design generates a self-contained web application for one or more agents and iterates on it conversationally, serving it locally with live reload. Join agent keys with +, for example io design support-bot+triage-bot, to use multiple agents in one application.
The command registers a Vectara bring-your-own LLM configuration using the Anthropic API key you supply. The key is not stored locally; the registration is tenant state.
The registration uses a fixed name and is tenant-wide, not personal. Another user on the tenant can use the existing registration without entering a new key. io design logout deletes that registration for everyone using it. Use io design rotate-key to replace the credential without removing the registration.
Your tenant must be entitled to register a customer LLM. Otherwise io design directs you to contact Vectara support to enable BYO-LLM.
Previewing an agent in a browser
io preview serves a minimal session page for an existing agent. A local process proxies the API requests, keeping your API key out of the browser page.
The preview server listens on the loopback interface and checks the request's host. It is a local testing surface, not a public deployment. Sharing the URL or exposing it under another hostname does not make it a supported shared preview.
Deployment and LLM requirements
Confirm the shared deployment and LLM requirements, especially in a self-managed environment. Installing the CLI does not enable io or configure a suitable LLM on the deployment.
FAQs
Why can a read-only print-mode request need setup first?
The requested task may be a read, but creating or refreshing the CLI's helper agent is a separate write. Without --auto-approve, print mode refuses that setup and exits 2. Provision deliberately with io bootstrap before retrying the task.
Why did my script start exiting with code 2 after a CLI upgrade?
An upgrade can change the bundled agent definition and require a refresh. Read the setup message and provision the CLI agent as needed. Do not add --auto-approve solely to suppress the exit code without reviewing its provisioning effects.
Does pressing Enter mean I accepted a recommendation?
It submits the highlighted option. That may be io's recommendation, but when there is no recommendation the first option is highlighted instead. Inspect the choice, move with the arrow keys, or press t to type an answer.
Can I share the local preview URL with a colleague?
It is not a public preview service. The server binds to loopback and accepts only its allowed local hostnames. Use it for local testing rather than treating the generated URL as a hosted application.
Is io design logout only a local sign-out?
No. It deletes the shared tenant-wide LLM registration described above. Consider other users of that registration before using it; use io design rotate-key when the intention is to replace the credential.