Vidbyte CLI

Vidbyte CLI: start hosted Research harness runs, run local Codex coding-agent teams, and get ranked next actions from your terminal.

vidbyte-cli is Vidbyte's terminal app for AI-agent work. It starts hosted, persistent research runs on Vidbyte's servers (the Vidbyte Research harness, whose agent is the Persistent Researcher), runs teams of local Codex coding agents on your machine (Ensemble Agent, Persistent Agent, Task Board, Stages Agent), and turns a goal into ranked, critic-reviewed next actions (Suggestion Agent). Its commands print JSON with --json, so Claude Code and Codex can drive it, and the agent skills (npx skills add cerredz/vidbyte-cli, https://vidbyte.pro/docs/cli/agent-skills) teach them how. The CLI is free and MIT-licensed. Hosted runs and local launch fees are paid from one prepaid Vidbyte API balance; local agents run their models on your own Codex or OpenAI account. Docs: https://vidbyte.pro/docs/cli.

Install

vidbyte-cli is published on PyPI and requires Python 3.11 or newer.

python -m pip install vidbyte-cli                  # into an activated virtual environment
pipx install vidbyte-cli                           # or: a global command in its own environment
pipx upgrade vidbyte-cli                           # move an existing pipx install to the latest release
vidbyte-cli --help

The step-by-step guide lives at https://vidbyte.pro/docs/cli/quickstart.

Log in

Create an API key at https://vidbyte.pro/settings/api, then run:

vidbyte-cli login                                  # guided: shows where to get a key, then a hidden prompt
printf '%s' "$VIDBYTE_KEY" | vidbyte-cli login --with-token   # scripts and CI: no prompt, no styling

The interactive prompt is styled with Rich and written to stderr, so stdout still carries only the one result line. --color never, NO_COLOR, and TERM=dumb keep it plain. vidbyte-cli provider login <provider> follows the same pattern.

If the CLI is useful to you, star it on GitHub from your terminal:

vidbyte-cli star              # stars through the GitHub CLI (gh) when it is logged in
vidbyte-cli star --browser    # or open https://github.com/cerredz/vidbyte-cli and click Star

Bugs and feature requests go to https://github.com/cerredz/vidbyte-cli/issues.

Install (development)

python -m venv .venv
source .venv/bin/activate                          # Windows: .venv\Scripts\activate
python -m pip install -e ".[dev]"
vidbyte-cli --help

The console command is vidbyte-cli. The reusable Python entry function returns an integer status; only the generated console wrapper and python -m vidbyte_cli terminate a process.

Global options

Root options precede the command: vidbyte-cli --format json --profile work research threads.

Option	Behavior
--format human|json|jsonl|none	Human, one-document, streaming, or suppressed results
--json	Alias for --format json; conflicts with any other --format value
--profile NAME	Select a configuration and credential scope
--no-input	Never prompt for interactive input
--color auto|always|never	Color preference, subject to terminal safety
--debug	Show redacted stack frames — never exception values, causes, or locals

Results are the only thing written to stdout; progress, warnings, diagnostics, and errors go to stderr. JSON and JSONL records carry schema_version and kind, and machine errors use that same envelope.

Every error also carries description, trace, and file_path — non-sensitive fields that let an agent calling this CLI diagnose and correct its own invocation.

A document printed by a recorded agent run also carries a top-level run_id, the id that vidbyte-cli runs show takes, beside schema_version and kind; it is never inside data, which stays the command's own. Documents from any other command have no run_id key.

Commands

Command	Purpose
vidbyte-cli login / logout / whoami	Manage the stored Vidbyte API key
vidbyte-cli billing balance	Show the spendable, available, and held Vidbyte API balance (free, never pays)
vidbyte-cli billing top-up --confirm [--idempotency-key KEY]	Add the $5.00 minimum API-balance credit through x402 (paid; needs the owner's approval)
vidbyte-cli research start <prompt>	Open a research thread and admit its first run
vidbyte-cli research add <thread_id> <prompt>	Add another run to an existing thread
vidbyte-cli research resume <run_id>	Continue a partial, failed, or out-of-credit run
vidbyte-cli research status <run_id>	Show one run's current status
vidbyte-cli research watch <run_id>	Follow one run until it settles
vidbyte-cli research threads	List your research threads
vidbyte-cli research thread <thread_id>	Show one thread and its rollup counters
vidbyte-cli runtime list	List local runtime primitives and admission prices
vidbyte-cli runtime doctor	Detect supported native coding-agent hosts
vidbyte-cli runtime adversarial-team <task>	Planned: checks the launch, then stops before any charge
vidbyte-cli runtime same-host-ensemble <task>	Run a role-differentiated agent ensemble on this machine
vidbyte-cli runtime persistence <task> [--strength 1-6]	Run one Codex session with 6–100 additional improvement turns
vidbyte-cli agents list	List runnable agent workflows and describe what each does
vidbyte-cli runs list [--all] [--agent ID] [--limit N]	List the agent runs still going on this machine (offline, free)
vidbyte-cli runs show <run_id>	Show one recorded run's request and output (offline, free)
vidbyte-cli runs last [--agent ID]	Show the newest recorded agent run (offline, free)
vidbyte-cli mcp serve [--workspace PATH]	Local MCP server that routes a request to one Vidbyte agent (needs the mcp extra)
vidbyte-cli config get|set	Manage CLI configuration
vidbyte-cli doctor	Diagnose CLI setup
vidbyte-cli setup-prompt	Print a detailed, permission-first install prompt for a coding agent
vidbyte-cli star [--browser]	Star the public repository on GitHub (only when you ask)
vidbyte-cli agents suggest run --goal "..." [--count 5]	Generate and independently critique ranked next-action ideas with handoffs
`vidbyte-cli agents suggest categories [--view-all	--view ID]`
vidbyte-cli agents suggest handoff --input result.json --idea idea-003	Extract one handoff packet (no model)
vidbyte-cli agents suggest project create --key KEY --title TITLE --description TEXT	Create a local suggestion-memory project (no model)
vidbyte-cli agents suggest project list	List local suggestion-memory projects (no model)
vidbyte-cli agents suggest feedback accept|reject --project KEY --suggestion TEXT [--reason TEXT]	Record explicit user feedback for a project (no model)
vidbyte-cli agents bug-finder run --github-repo OWNER/NAME --project-type web|cli|sdk [--app-url URL] [--max-bugs N] [--linear]	Hunt a GitHub repository for bugs, one fresh Codex agent per bug, with one artifact per bug and, with --linear, one Linear issue per bug
vidbyte-cli agents bug-finder mark --github-repo OWNER/NAME --bug ID --state STATE	Set one bug's state in a repository's bug ledger (no model)
vidbyte-cli agents bug-finder sync --github-repo OWNER/NAME [--linear-workspace WS] [--linear-team KEY]	File a ledger's open bugs as Linear issues, never the same bug twice (no model)
vidbyte-cli agents infinite-memory run [TASK] [--prompt-file FILE] [--workspace DIR] [--seed FILE] [--no-sync] [--max-cost-usd USD]	Run the InfiniteMemoryAgent on a task here and print its handoff. Model calls bill your Vidbyte key at the model's rate + 2% (an exported OPENAI_API_KEY is relayed on OpenAI models). Unless --no-sync, the task, events, handoff and notes stay in your account 90 days; raw model turns never leave. Its shell runs as you: it can read your files, keyring and unlisted secrets, and sees OPENAI_API_KEY but no Vidbyte or other provider key. --max-cost-usd (default 5) counts priced calls before the fee; running pairs can pass it. About one busy synced run per key fits the sync rate limit
vidbyte-cli agents infinite-memory resume --run-id RUN_ID [--workspace DIR] [--no-sync] [--max-cost-usd USD]	Continue a stopped infinite-memory run (model calls billed like run: rate + 2%), or only finish uploading a finished one (no model call)
vidbyte-cli github link	Link a GitHub account through GitHub's device flow; the token stays in the system keyring
vidbyte-cli resolve setup --repo OWNER/NAME --harness opencode|grok|muse [--harness-model M] [--every MINUTES] [--check CMD] [--skill PATH]	Propose a scheduled merge-conflict resolver workflow, its two sealed secrets, and its label in each repository of one owner
vidbyte-cli resolve run --repo OWNER/NAME --harness opencode|grok|muse [--max-prs N] [--recent] [--parallel-number N]	Resolve one repository's conflicting pull requests once with a coding agent, as the scheduled workflow does
vidbyte-cli browserbase login [--with-token]	Check and store the Browserbase API key web bug hunts use for their cloud browser
vidbyte-cli linear login [--with-token]	Check a Linear personal API key and store it for the workspace it belongs to
vidbyte-cli linear logout [--workspace WS]	Remove one connected Linear workspace's key and record
vidbyte-cli linear workspaces	List the connected Linear workspaces and the default (offline)
vidbyte-cli linear use WORKSPACE [--team KEY]	Choose the default Linear workspace and, optionally, its default team
vidbyte-cli linear teams [--workspace WS]	List a connected Linear workspace's teams, live from Linear
vidbyte-cli slack add NAME	Save a Slack incoming-webhook URL, read from stdin or a hidden prompt, under NAME for --send-to slack:NAME
vidbyte-cli slack list	List the saved Slack webhook names, never the URLs (offline)
vidbyte-cli slack remove NAME	Forget one saved Slack webhook; an unknown NAME changes nothing
vidbyte-cli resend login [--with-token]	Check and store a Resend API key, reporting full or sending-only access
vidbyte-cli agentmail login [--with-token]	Check and store an AgentMail API key
vidbyte-cli mailgun login [--with-token]	Check and store a Mailgun account API key
vidbyte-cli mailchimp login [--with-token]	Check and store a Mailchimp Marketing API key
vidbyte-cli brevo login [--with-token]	Check and store a Brevo API key
vidbyte-cli klaviyo login [--with-token]	Check and store a Klaviyo private API key
vidbyte-cli sendgrid login [--with-token]	Check and store a SendGrid API key
vidbyte-cli ses login --access-key-id ID --region REGION [--with-token]	Check and store an Amazon SES IAM access key for one region
vidbyte-cli gmail login	Sign in to Gmail in the browser and store a send-only grant
vidbyte-cli outlook login	Sign in to Outlook in the browser and store a send-only grant

The Resend and email provider logins check a credential with the provider and keep it in the system keyring only; nothing reads it back yet. The six key logins and ses login read the secret from a hidden prompt or, with --with-token, from stdin. gmail login and outlook login ask only for permission to send email, through an OAuth app you register yourself: set VIDBYTE_GMAIL_CLIENT_ID, plus VIDBYTE_GMAIL_CLIENT_SECRET, which Google requires for Desktop app clients, or VIDBYTE_OUTLOOK_CLIENT_ID. The consent link opens in your browser and is also printed on stderr; the login waits up to 5 minutes for approval.

Universal agent options

Every agent command (agents suggest run, agents bug-finder run, agents infinite-memory run and resume, runtime same-host-ensemble, runtime persistence, runtime task-board run, and runtime stages run) accepts the options below, with the same spelling and validation. --model, --reasoning-effort, and --instructions are checked, and the instruction files are read, before any credential lookup, paid admission, or model call; an invalid value exits with status 2 as INVALID_ARGUMENT, and nothing is charged. --send-to targets and their credentials are checked next, still before any admission or model call. The values are never sent to Vidbyte, except that a synced agents infinite-memory run stores its --model. The runs ledger keeps --model and --reasoning-effort in each run's record, but never the --instructions file paths or the --send-to targets, and no task-board checkpoint keeps any of them, so a task-board resume needs them passed again.

Option	Default	Meaning and reach
--model MODEL	installed Codex default (suggestion: gpt-6-sol)	The model id the agents run on. Suggestion: the generator only, while --critic-model keeps choosing the critic. Ensemble: every turn and fork. Persistence: the agent. Task board: every task agent. Stages: every stage whose --stage-model is omitted or empty. Bug finder: every hunt agent. Infinite memory: every agent of the tree, on the model's own provider.
--reasoning-effort	provider default (suggestion: high; stages: medium)	none, minimal, low, medium, high, or xhigh for every agent the command starts; an empty value means unset. In stages it applies only when --stage-effort is omitted. Infinite memory refuses it.
--instructions FILE	none	Repeatable. Each Markdown or text file is appended, after a blank line, to the system prompt of every agent the command starts, ensemble forks and suggestion critics included. An ensemble fork also gets the text at the end of its first turn. At most 8 non-empty UTF-8 files and 20,000 bytes in total; errors name the file's position, never its path or contents.
--send-to TARGET	none	Repeatable. slack posts to the webhook in SLACK_WEBHOOK_URL; slack:NAME to the one saved with slack add NAME; github:OWNER/NAME opens an issue with GITHUB_TOKEN, else the github link account; linear or linear:TEAM opens an issue with the linear login key, in the default team unless TEAM is given. The result is sent after a normal finish, with one receipt line per target on stderr and stdout unchanged. A failed send exits 1 after every target was tried, with the result still on stdout. A dry run or prompt preview sends nothing. Needs a vidbyte-sdk release with the output connectors.

Instruction files carry developer-instruction authority over every agent the command starts, including agents that can edit your workspace, so pass only files you wrote or reviewed. Their text is repeated in every agent's prompt, which multiplies its token cost on large runs.

Turn a goal into ranked, critiqued next actions (Suggestion Agent)

The Suggestion Agent drafts next actions for one goal, has an independent critic review them, and returns the survivors ranked, each with a handoff.

agents suggest run takes one nonempty --goal plus optional repeated context and --files values. It takes no JSON input file. Both roles default to gpt-6-sol on the openai provider at high reasoning effort: --model sets the generator's model, including its extra-compute generators, --critic-model independently sets the reviewer's, and --reasoning-effort replaces the effort for every role. --count accepts 2–100, --rounds accepts 1–8, --max-output-tokens caps each reply at up to 128,000 tokens (default 32,000), and --extra-compute runs one focused generator context per selected category before critique. --dry-run, categories, handoff, project, and feedback never call a model, so they need no key and are never charged.

The suggestion agent is usage-based: there is no per-suggestion price. Every generator and critic turn is one call to Vidbyte's model gateway (POST /api/v1/models/generate), billed to the balance of your stored Vidbyte key at that model's rate in the Vidbyte SDK pricebook plus 2%. A default run makes about five calls: a first draft, then a critique and a revision per round. The key needs the models:invoke permission (vidbyte-cli login with a key created at https://vidbyte.pro/settings/api); no Codex install, OpenAI login, or OpenAI key is involved. The goal, its context, --files bodies, attachments, and loaded project memory are sent through Vidbyte to OpenAI on each call. The result's usage field reports the model calls and the input, output, and cached tokens the run used; the billed amounts appear at https://vidbyte.pro/usage. --max-total-tokens and --timeout-seconds are checked before each call, never mid-call, because a call in flight is billed when it completes. If the balance or the key's daily model-spend cap runs out after a slate exists, the run stops with gateway_limit and returns the latest reviewed slate; before that, it fails with the balance or rate-limit error.

Context is limited to 5,000,000 characters per item and in aggregate, with truncation or omission recorded in the result manifest. Each surviving idea carries one primary category, evidence references, decisions, eight-to-ten considerations, completion checks, and a deterministic handoff whose authority is not granted by the handoff itself.

Suggestion projects are optional local JSON memory. The catalog is stored in the platform-native Vidbyte data directory as suggestions/projects.json, and each project links to one file under suggestions/projects/ holding its ordered accepted and rejected feedback. Create a project once, pass --project KEY to a run to load its title, description, and feedback as context, then record the user's explicit reactions with the feedback commands the run prints. Silence, ambiguity, and unrelated implementation are never acceptance or rejection. Without --project, a run reads no project file.

vidbyte-cli agents suggest project create \n  --key vidbyte-cli \n  --title "Vidbyte CLI" \n  --description "The local CLI and agent runtime."
vidbyte-cli agents suggest run --project vidbyte-cli --goal "Choose the next CLI improvement."
vidbyte-cli agents suggest feedback reject \n  --project vidbyte-cli \n  --suggestion "Use MongoDB for project memory" \n  --reason "It adds unnecessary backend infrastructure."

Bug finder agent

agents bug-finder run --github-repo OWNER/NAME --project-type web|cli|sdk hunts a GitHub repository for bugs in a fresh shallow clone that is deleted when the run ends. Each turn, one fresh Codex agent reports one new bug with full evidence or reports nothing new; the run stops there, at a bug already in the ledger, or after --max-bugs (1–50, default 5) bugs. A web hunt also needs --app-url and a Browserbase key stored with browserbase login. Each bug gets a JSON and a Markdown ticket under bug-finder/projects/OWNER/NAME/ in the Vidbyte data directory, and agents bug-finder mark sets its ledger state offline.

github link uses GitHub's device flow: approve the printed one-time code on github.com, and the token is kept in the system keyring only. Set VIDBYTE_GITHUB_CLIENT_ID to the client ID of a GitHub OAuth app or GitHub App with device flow enabled.

linear login connects one Linear workspace per personal API key and keeps the key in the keyring. linear workspaces, linear use WORKSPACE [--team KEY], linear teams, and linear logout list, choose, inspect, and forget connected workspaces. With --linear, or --linear-workspace or --linear-team, each new bug is filed as a Linear issue the moment it is recorded, with a priority from its severity, and a regression adds one comment. The issue id is saved in linear.json before Linear is asked, so a retry never files a bug twice, and agents bug-finder sync files every open bug that has no issue yet.

The agent runs repository code in Codex's workspace-write sandbox on your own Codex login, with Vidbyte keys, CODEX_API_KEY, and non-OpenAI provider keys blanked. Code it runs can still read OPENAI_API_KEY, any other secret in your environment (such as GITHUB_TOKEN or AWS_*), and the plaintext fallback credential files in the Vidbyte data directory, so run it on a machine or account that does not hold them.

Merge-conflict resolver

resolve setup --repo OWNER/NAME --harness opencode|grok|muse proposes a scheduled GitHub Actions workflow in each repository, through a setup pull request you merge yourself, and seals VIDBYTE_RESOLVE_GITHUB_TOKEN and VIDBYTE_RESOLVE_API_KEY into its Actions secrets. Every --every minutes (default 15) the workflow runs resolve run, which merges each conflicting pull request's base branch into its branch, asks the coding agent to resolve the conflicted files, runs --check, and pushes the merge commit. A pull request it cannot resolve gets one comment and the needs-human-resolve label; remove the label or push a commit to retry it. resolve run needs git 2.38 or newer, for git merge-tree --write-tree; with an older git it fails every pull request it would examine, writes nothing to any of them, and exits 1, while a run with nothing to examine still exits 0.

The fine-grained token needs Contents, Pull requests, Workflows, and Secrets read and write on only the repositories you name, and one setup covers one owner. Code that runs in this repository's Actions with this token can push to every repository it covers, add a workflow that prints every Actions secret of those repositories, and overwrite those secrets. One token per repository contains that to one repository. Every scheduled run bills Actions minutes even with nothing to do: at every 15 minutes that is about 2,880 job starts a month, each at least one billed minute in a private repository. Model usage bills your own key, and GitHub pauses schedules in a public repository after 60 days without activity.

Persistent deep research from the terminal, alongside Claude Code or Codex (Research harness)

Start a run from your terminal, or let Claude Code or Codex start it with --json; it keeps going after the terminal closes.

research commands start and follow runs of the Vidbyte Research harness, whose agent is the Persistent Researcher. Research runs on Vidbyte's servers. It is not a local skill, and the /research learning skill is unrelated. This CLI admits runs, reads their durable status, and lists the threads you own; deep dives, artifact bodies, sources, and exports remain website-only.

A thread is addressed only by the public ID that research start and research threads print. That is the value to pass back to research add and research thread; the internal identifier some other tools show is rejected before a request is sent.

research status and research watch report state, phase, continuation count, and a timestamp — the whole of what the API publishes for a run. Neither prints a thread ID, because the status route does not carry a usable one.

Starting, adding, and resuming are priced and idempotent. Each sends a generated Idempotency-Key and reports it, so --idempotency-key <that value> retries a mutation whose outcome you did not see without paying for it twice. research watch polls every ten seconds and backs off from there: API keys are metered on a weighted per-minute budget, and polling harder can exhaust the budget you need to start the next run.

Local runtime primitives

runtime commands execute on your machine, driving a native coding agent you already installed. Vidbyte charges a small flat admission fee for the orchestration; the model usage runs against your own provider subscription, not ours.

The base install already includes the Codex integration these commands use, so there is no extra package to install.

Run several Codex agents in parallel and implement the best approach (Ensemble Agent)

runtime same-host-ensemble <task> runs four stages on one machine. A planner agent reads your task and generates the ensemble's roles, writing each role's complete system prompt. Each role then runs concurrently in its own read-only fork and returns 5 to 10 distinct approaches, each with its pros, cons, risks, and the files it would touch. A role cannot edit anything — the sandbox forbids it, not just the prompt. A selector fork then narrows every approach from every role down to one, in rounds: each round keeps a fifth of what it was given, weighs the pros and cons of every candidate it keeps, and records why the rest were dropped. Finally one write-enabled fork receives the selected approach and the selector's brief, and does the work. That last fork is the only agent in the topology permitted to modify your workspace.

Option	Default	Meaning
--host	codex	The only accepted value: Codex is the one host with verified thread-fork and per-fork sandbox support.
--roles	3	How many specialist roles the planner invents for this task (3-100). More roles widen the approach slate the selector narrows.
--model, --reasoning-effort, --instructions	see Universal agent options	Reach every turn and fork in the run.
--idempotency-key	generated	Reuse a key to retry a priced admission without being charged twice. Omit to generate one per invocation.

A role that times out (after a fixed 300-second bound) or fails is reported in the result and the run continues. The run stops only when every role failed.

Two costs are worth separating. Admission is two cents, charged once, after the CLI has confirmed your input, the SDK, and the host — so a missing Codex never costs you anything. The grant is then verified through the layered runtime gate before any agent starts; a rejected grant fails the run without starting a single fork. The larger cost is your own provider usage: the SDK opens a fresh Codex app-server per turn and per fork, so a three-role run is roughly a dozen of them against your subscription, and --roles 100 is a thousand approaches for the selector to read. Raise it deliberately.

Keep a Codex session working past its first answer (Persistent Agent)

The Persistent Agent gives one Codex session your task, then a fixed number of further turns that ask it to check and improve its own work.

vidbyte-cli login
vidbyte-cli provider login openai
vidbyte-cli runtime persistence "Your exact task" --strength 1

Install Codex on PATH first. OpenAI credentials resolve from OPENAI_API_KEY, then the selected profile's keyring or approved file fallback. They are passed only to the Codex child; native Codex login is unchanged. The configured Codex model, or the one --model names, must be available to that OpenAI API key.

Strength tiers 1–6 send 6, 8, 20, 40, 70, 100 additional turns, after the exact original task. All turns resume the same explicit session ID. --host auto selects Codex; other hosts are unsupported. Codex runs with workspace-write sandboxing, without a sandbox bypass.

Each invocation costs two cents from the Vidbyte API wallet, plus your OpenAI usage. Task text and provider credentials never enter Vidbyte admission requests.

Use a caller-chosen --idempotency-key (8–128 allowed characters) to recover an uncertain admission request without another debit. Reusing it does not resume local work: a new CLI invocation starts a new Codex session, so do not rerun a completed task with a recovery key. Ctrl+C cancels the active SDK turn and closes its Codex connection. A failed or hour-long turn stops the loop; completed local work remains, and the flat admission fee is not automatically refunded. This is a foreground loop, not a daemon that survives terminal closure.

Only the final response is written to stdout; progress goes to stderr. JSON output includes session_id, continuation_turns, and text in the standard result envelope.

Runs ledger

vidbyte-cli runs list
vidbyte-cli --json runs last

Eight agent commands record every run they start on this machine: agents suggest run, agents bug-finder run, agents infinite-memory run, agents infinite-memory resume, runtime persistence, runtime same-host-ensemble, runtime task-board run and runtime stages run. Research runs are not recorded; their status lives on the backend.

A recorded run prints its id. With --json, the result document, or the error envelope on stderr, carries it as the top-level run_id. With --format jsonl, the first record is a runs.started document naming the run, and every record after it carries the same run_id. Human output prints Run ID: <id> on stderr when the run starts, and a human error repeats it, so stdout keeps only the result. If the ledger cannot record the run, the run still works, prints one warning, and carries no id.

Each run is one JSON file. It holds the request (the command, the working directory and the parsed options), the one result document the run printed or the error envelope it failed with, and the run's status, process id, start time and finish time. Nothing else is saved: no progress messages, no admission details, never the value of an idempotency key, and never the --instructions file paths.

Records live in the runs directory of the CLI's per-user state directory: %LOCALAPPDATA%\Vidbyte\vidbyte-cli\runs on Windows, ~/.local/state/vidbyte-cli/runs on Linux and ~/Library/Application Support/vidbyte-cli/runs on macOS, or under $XDG_STATE_HOME/vidbyte-cli when that variable is set. vidbyte-cli --json runs list prints the exact path as runs_dir. Task text is saved as you typed it, so treat the directory like your shell history.

vidbyte-cli runs list shows the runs still going: running means the process is alive, and abandoned means the run's outcome was never recorded, because its process died or it could not save its final state, so its work may still have finished. vidbyte-cli runs list --all adds finished runs (succeeded, failed, interrupted), newest first. vidbyte-cli runs show takes a run id or a unique prefix of it.

The read verbs are offline and free and need no API key. Write --json before runs, because it is a root option. There is no retention: records accumulate until you delete them. To remove a run, delete its .json file and any .lock file of the same name from the runs directory while no recorded run is live.

Use Vidbyte agents from Claude Code or Codex

vidbyte-cli mcp serve is a local Model Context Protocol server. Your coding agent describes what you need; Jev, TypeSafe's decision model, which Vidbyte runs (the model behind JevAgent), picks the Vidbyte agent that fits on Vidbyte's backend; and the agent runs from this CLI on your own machine. The coding agent never writes or runs a vidbyte-cli command itself: every command the server starts comes from a fixed allowlist, with your request as its task text.

Register it with one command (needs uv; works the same on Windows, macOS, and Linux):

claude mcp add --scope user vidbyte -- uvx --from "vidbyte-cli[mcp]>=0.3.0" vidbyte-cli mcp serve
codex mcp add vidbyte -- uvx --from "vidbyte-cli[mcp]>=0.3.0" vidbyte-cli mcp serve

Without uv, register pipx run --spec "vidbyte-cli[mcp]>=0.3.0" vidbyte-cli mcp serve instead. The >=0.3.0 bound matters: uvx and pipx run reuse a cached environment that satisfies the requirement, and releases before 0.3.0 have no mcp serve. Codex gives a server ten seconds to start by default, and the first uvx launch downloads the package, so set startup_timeout_sec = 60 under [mcp_servers.vidbyte] in ~/.codex/config.toml. Pass --workspace <project root> after serve when your client does not start servers in the project directory; Claude Code's CLAUDE_PROJECT_DIR is used otherwise.

Never put an API key in the registration command (for example -e VIDBYTE_API_KEY=...): clients store that command in plain text. When a key is missing, the server opens a page on 127.0.0.1 in your browser where you paste it; the key is verified, stored in your operating-system keyring, and never passes through the chat. If your client cannot open that page, the tool tells you to run vidbyte-cli login (and vidbyte-cli provider login openai for the persistence or task-board agent) in a terminal. If Codex stops waiting while the page is open, finish the page and call the tool again; the stored key is used from then on. Any Vidbyte account, the free plan included, can create an API key at https://vidbyte.pro/settings/api.

Tool	What it does	Cost
vidbyte_setup_status	Reports which keys and hosts are missing	Free, offline
vidbyte_plan(request)	Asks Jev one yes/no question per agent and stores a 30-minute plan	One metered Jev call billed to your Vidbyte balance
vidbyte_run(plan_id, request_id)	Runs the plan's recommended (or another passing) agent; your client asks you first	The agent's own price: ensemble, persistence, and task board charge a two-cent admission plus OpenAI usage; suggestion bills each model call to your Vidbyte balance at its model's rate plus 2%; research is usage-based up to $5.00
vidbyte_run_status(job_id)	Reports a job's status and pages its result	Free, offline
vidbyte_cancel_run(job_id)	Stops a running job	Free; an admission or completed model calls are not refunded

The routed agents are the suggestion agent, the same-host ensemble, the persistence agent, research, and the task board. The ensemble, persistence, and task-board agents edit files in the workspace, and only one file-writing agent runs in a workspace at a time. The task board can divide one broad request into up to five independent tasks and runs them sequentially; each task agent uses the same workspace and your stored OpenAI key. Task-board jobs can run for up to 30 days and can be stopped with vidbyte_cancel_run. A research job completes when Vidbyte accepts the run; follow it with vidbyte-cli research watch <run_id>. A job whose server stopped reads as interrupted and is never restarted automatically. Local state lives in the CLI's state directory under mcp/; remove the server with claude mcp remove vidbyte or codex mcp remove vidbyte.

Configuration

Variable	Meaning
VIDBYTE_API_URL	API host (default https://vidbyte-backend.onrender.com)
VIDBYTE_API_KEY	API key; overrides the stored credential for the current shell
VIDBYTE_PROFILE	Profile name; the lower-precedence equivalent of --profile
VIDBYTE_OUTPUT_FORMAT / VIDBYTE_COLOR	Presentation defaults
VIDBYTE_REQUEST_TIMEOUT_SECONDS	Per-request timeout

Non-secret settings resolve command option → environment → selected profile → default profile → built-in, and vidbyte-cli config get <key> reports both the effective value and which layer supplied it. config set accepts api_url, output_format, color, and request_timeout_seconds.

API keys resolve separately: environment → OS keyring → permission-restricted file. An environment key is never persisted, and the restricted file is used only with explicit consent. Configuration, cache, state, and data live in the platform's standard application directories; ~/.vidbyte/ is still read, and is copied across by a verified migration that leaves the originals in place.

Architecture

Status: persistence requires a backend deployment with persistence activation and grant verification. Adversarial-team is planned (no executor yet).

Local runtimes are separate from hosted harnesses. Vidbyte authenticates a launch and charges a flat admission fee from the API-key wallet, while persistence executes in Codex using the caller's OpenAI API key. x402 funds that wallet through the backend's POST /agent/topup route; machine environment and repository contents are never uploaded for admission.

Every command is static and known at release time. Runtime discovery adds one authenticated catalog route. Persistence calls activation and authenticated grant verification before launching Codex.

The application composition root lives in src/vidbyte_cli/lib/runtime. It constructs one invocation context, binds stdin/stdout/stderr through lib/io, resolves output and error policy, and builds the Click tree.

Verify

python -m pip install -e ".[dev]"
python scripts/run_ci.py

The canonical gate runs Ruff lint/format checks, strict mypy, byte compilation, offline command smoke checks, sdist/wheel build, Twine metadata validation, and an installed-wheel smoke check. GitHub Actions invokes the same script on Linux, Windows, and macOS.

Releasing

Bump version in pyproject.toml, and both versions in server.json (the MCP Registry entry), in one pull request. PyPI versions are permanent, so the bump is the release decision. While GitHub Actions cannot run here, release from a clean main with python scripts/release_local.py (gh signed in, a vidbyte-cli PyPI token in PYPI_API_TOKEN; --dry-run publishes nothing). It runs the gate above, uploads exactly the files it verified, then tags v{version} and creates the GitHub Release on the public cerredz/vidbyte-cli. When Actions runs, tag-release.yml and release.yml do the same.

API balance

vidbyte-cli billing balance
vidbyte-cli --json billing balance

billing balance shows what the configured key can spend. The read is free, never pays, and answers even on an empty wallet, so check it first when a call fails for lack of balance. spendable_balance_cents is what a new call can draw on: the available balance minus what runs in progress are holding. vidbyte-cli billing top-up --confirm adds the $5.00 minimum through x402, and only with the account owner's approval. Out of balance mid-run, agents infinite-memory exits 5 with its spend and resume command.

Runtime admission payments

vidbyte-cli runtime persistence "your task" uses your authenticated Vidbyte API balance by default. The flat $0.02 admission is recorded as ordinary API usage. Local Codex model usage is still paid through your OpenAI credentials.

To pay the admission directly with x402, set VIDBYTE_X402_PRIVATE_KEY in your shell and run vidbyte-cli runtime persistence "your task" --with-x402-payment. A Vidbyte API key with runtime:write is required for ownership in both modes. VIDBYTE_X402_NETWORK defaults to Base (eip155:8453); Base Sepolia (eip155:84532) is supported for testing. Keep private keys out of command arguments. The wallet must already hold the network's USDC; the CLI does not fund it.

Both modes verify the signed receipt against Vidbyte's database before launching Codex. The API-balance path also verifies the exact usage-ledger debit. Payment credentials are not passed to Codex. The CLI never switches payment methods automatically. Recover a failed admission with the same --idempotency-key; a retry preserves the original grant and expiry. An uncertain payment outcome must be reconciled before starting another purchase. Verification does not refund a failed local execution.