About five minutes
Install and run vidbyte-cli
Go from a fresh Python environment to a signed-in CLI whose local checks pass, ready to run your first agent. Every vidbyte-cli command on this page works in the published release on PyPI (0.3.4).
- Codex
- Claude Code
- OpenCode
- Grok
- Gemini
Let your agent set up vidbyte-cli
Copy a step-by-step prompt for an agent to install the CLI, verify your setup, and walk you through the next safe step. It checks what is already configured first and asks before installing software, handling credentials, or starting paid work.
Get the same prompt from your terminal (vidbyte-cli 0.3.4 or newer)
CLI setup prompt
vidbyte-cli setup-promptInstall vidbyte-cli from PyPI
The CLI requires Python 3.11 or newer. Install it into a virtual environment so its dependencies stay separate from your other Python projects. Pick your operating system.
Create a virtual environment
Creates an isolated Python environment in a
.venvfolder in the current directory, so the CLI never touches your system Python. On some systems the interpreter is namedpython3instead ofpython.Create
bashpython -m venv .venvActivate it
Points
pythonandpipat the virtual environment for this terminal session. Run it again whenever you open a new terminal.Activate
bashsource .venv/bin/activateInstall the CLI
Downloads the latest release from PyPI and adds the
vidbyte-clicommand. Calling pip throughpython -mmakes sure the install lands in the environment you just activated.Install
bashpython -m pip install vidbyte-cliConfirm the installed version
Prints the installed release number, which proves
vidbyte-cliis on your PATH and tells you which version you are running.Verify
bashvidbyte-cli --version
Create a virtual environment
Creates an isolated Python environment in a
.venvfolder in the current directory, so the CLI never touches your system Python. On some systems the interpreter is namedpython3instead ofpython.Create
bashpython -m venv .venvActivate it
Points
pythonandpipat the virtual environment for this PowerShell session. If PowerShell refuses to run the script, runSet-ExecutionPolicy -Scope CurrentUser RemoteSignedonce, then activate again.Activate
bash.venv\Scripts\Activate.ps1Install the CLI
Downloads the latest release from PyPI and adds the
vidbyte-clicommand. Calling pip throughpython -mmakes sure the install lands in the environment you just activated.Install
bashpython -m pip install vidbyte-cliConfirm the installed version
Prints the installed release number, which proves
vidbyte-cliis on your PATH and tells you which version you are running.Verify
bashvidbyte-cli --version
List the available commands
Shows the top-level commands and the root options, such as --format, --profile, and --no-input, which always come before the command name. Add --help after a group, such as vidbyte-cli runtime --help, to see its subcommands.
Inspect
vidbyte-cli --helpUpgrade to the latest release
Replaces the installed CLI with the newest version published on PyPI. Run it inside the same environment you installed into.
Upgrade
python -m pip install --upgrade vidbyte-cliPrefer a global command? Install with pipx
pipx installs the CLI into its own managed environment and puts vidbyte-cli on your PATH, so it works in every terminal without activating anything. Update it later with pipx upgrade vidbyte-cli.
pipx
pipx install vidbyte-cliSign in to Vidbyte
API-backed research uses your Vidbyte account's usage balance. Local runtime admission also uses that balance by default, while model usage stays billed to your own provider account.
Log in with your Vidbyte API key
Prompts for your key without echoing it, verifies it with Vidbyte, and stores it only when verification succeeds. Create a key on the API Keys settings page first.
Log in
bashvidbyte-cli loginCheck which account is active
Shows the account the stored key belongs to. Run it before sending paid research work so you know which balance will be charged.
Verify
bashvidbyte-cli whoami
Check local runtime prerequisites
The base install is enough for hosted research. Local runtimes also need the codex command on your PATH, which pip does not install. In the released CLI (0.3.4) the Suggestion Agent runs on the Codex or Claude Code you install and sign in to. Run the doctor and catalog commands before any paid admission.
Install the Codex CLI (local agents only)
Local runtimes drive the
codexcommand on your PATH, which pip does not install; sign it in once withcodex login, the same sign-in the Suggestion Agent uses when it runs on Codex. Thevidbyte-cli[codex]extra adds nothing, because the base install already includes the SDK's Codex integration. If you only run hosted research, skip this step.Optional install
bashnpm install -g @openai/codexDiagnose the local host
Reports whether a coding-agent host that local runtimes drive (
codex,claude, oropencode) is on your PATH. It is read-only and offline, and it never reads your credentials or repository contents.Diagnose
bashvidbyte-cli runtime doctorList local runtimes and prices
Fetches the current catalog of local runtime primitives, with the price and supported host for each, so you can see what a run costs before you start one.
Catalog
bashvidbyte-cli runtime list
Set up a model key for local execution
The stages, persistence, and task-board runtimes require a stored OpenAI model API key. The same-host ensemble and the Suggestion Agent do not read it: they run on Codex's own sign-in, and from 0.3.4 the Suggestion Agent can run on Claude Code's sign-in instead.
Store your OpenAI key
Run provider login to enter the key through a hidden prompt; the CLI verifies it before storing it.
Model key
bashvidbyte-cli provider login openaiVerify the stored model key
Rechecks that the CLI's OpenAI key still works and shows where it comes from (the environment, the keyring, or a restricted file), without displaying the key.
Model key check
bashvidbyte-cli provider whoami openai
No released CLI reads a GitHub repository, a Slack channel, or a Drive file as context yet. A model key is not a platform connection.