Run agents from your terminal
Run Vidbyte from your terminal
vidbyte-cli is Vidbyte's terminal app (Python 3.11+; install it with pipx install vidbyte-cli or python -m pip install vidbyte-cli). It starts hosted Research harness runs (vidbyte-cli research start), runs teams of local Codex coding agents (Persistent Agent and Ensemble Agent), and turns a goal into ranked next actions with the Suggestion Agent. Agent skills (npx skills add cerredz/vidbyte-cli) let Claude Code or Codex drive it for you. Start with the quickstart, then run your first agent.
One terminal app for hosted and local work
The CLI signs in with a Vidbyte API key. Research runs on Vidbyte's servers, while local runtime commands drive a coding agent installed on your computer.
Hosted research — Open and continue Research harness threads on Vidbyte's servers, then read each run's status while it works.
Local runtimes — Run Codex on your computer as a small team, a task board, or one persistent session.
Platform connections — Not available yet: no released CLI reads a repository, pull request, Slack channel, or Drive file as context. GitHub linking for the bug finder is included in the released CLI (0.3.4).
Profiles and configuration — Keep separate accounts and settings, and switch results to JSON for scripts.
What do I need to run it?
Python 3.11 or newer, a Vidbyte account, and a Vidbyte API key. Local coding agents also need the codex command on your PATH, which pip does not install; vidbyte-cli runtime doctor checks for it. In the released CLI (0.3.4), next-step ideas need a key with the runtime:write permission (an admin or full-access key also works), balance for the suggestions you ask for, and Codex or Claude Code installed and signed in on your computer.
What does it cost?
Hosted research is paid from your Vidbyte API balance. Local coding agents charge a fee per run from that balance: $0.01 for stages, $0.02 for the same-host ensemble, persistence agent, and task board. The adversarial team is coming soon; its listed fee is $0.25 and nothing is charged until it launches. The model work is billed to your own OpenAI account or Codex subscription. For next-step ideas, the released CLI (0.3.4) charges 1 cent per suggestion you ask for before the run starts, OpenAI or Anthropic bills the model use to your own account through Codex or Claude Code, and a dry run is free.
Is there a CLI that runs persistent deep research from the terminal?
Yes. vidbyte-cli research start "<question>" starts a hosted Research harness run on Vidbyte's servers, so it keeps going after you close the terminal. Each run belongs to a thread: add a follow-up with research add, or follow progress with research watch. Put --json before the command so Claude Code or Codex can start and follow the run.
Can I run several Codex agents in parallel and keep the best approach?
Yes. vidbyte-cli runtime same-host-ensemble "<task>" --roles 3 runs 3 to 100 read-only Codex specialists at once, each proposing approaches in its own fork. A selector narrows them to one, and a single Codex agent implements it in your workspace.
Can an agent turn a goal into ranked, critiqued next actions?
Yes. vidbyte-cli agents suggest run --goal "<goal>" drafts next actions for the goal, has an independent critic reject weak and redundant ones, and returns the survivors ranked, each with its evidence. --count sets how many come back (default 5, from 2 to 100) in the released CLI (0.3.4), where Vidbyte charges 1 cent for each one you ask for.
Keep your credentials apart
The CLI uses separate credentials, each with its own command. Your Vidbyte key identifies your account and a model key runs local work. A GitHub link lets the bug finder clone your repositories and --send-to github:OWNER/NAME post a result as an issue. Integrations such as Linear, Browserbase, Slack webhooks, Resend, and email providers each have their own login command.
- Vidbyte API key
- What it is forIdentifies your Vidbyte account
- Set it up with
vidbyte-cli login - Model API key
- What it is forRuns models for the stages, persistence, and task-board runtimes
- Set it up with
vidbyte-cli provider login openai - GitHub link
- What it is forLets the bug finder clone your repositories and
--send-to github:OWNER/NAMEopen an issue - Set it up with
vidbyte-cli github link
| Credential | What it is for | Set it up with |
|---|---|---|
| Vidbyte API key | Identifies your Vidbyte account | vidbyte-cli login |
| Model API key | Runs models for the stages, persistence, and task-board runtimes | vidbyte-cli provider login openai |
| GitHub link | Lets the bug finder clone your repositories and --send-to github:OWNER/NAME open an issue | vidbyte-cli github link |
Start here
These pages are the shortest route from a fresh install to an agent doing real work.
Quickstart
Run your first agent
Agent skills
Platform connections
Check what's installed
Use vidbyte-cli --help to inspect the installed command tree. Results are written to stdout; progress, diagnostics, warnings, and errors go to stderr.
Inspect the installed CLI
vidbyte-cli --help
vidbyte-cli --version
vidbyte-cli doctor
vidbyte-cli runtime doctorRoot options come first — Options such as
--format,--profile, and--no-inputgo before the command name.JSON output —
--format jsonswitches results to JSON records for scripts and agents.Profiles —
--profile workkeeps a separate set of credentials and settings under a name.