Install and run vidbyte-cli
Follow this path from a fresh CLI checkout to a successful Vidbyte research request or local runtime launch. The commands use the source installation documented by the CLI repository.
1: Install from a clean Python environment
The CLI requires Python 3.11 or newer. Clone the repository, create a virtual environment, activate it for your shell, and install the package in editable mode. The Windows PowerShell activation line is included beside the macOS and Linux command so the setup stays explicit.
Shell
Install vidbyte-cli
git clone https://github.com/cerredz/Vidbyte-cli.git
cd Vidbyte-cli
python -m venv .venv
# macOS or Linux
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\Activate.ps1
python -m pip install -e .
vidbyte-cli --help2: Authenticate with Vidbyte
Run `vidbyte-cli login` and paste the Vidbyte API key into the hidden prompt. The CLI verifies the key before storing it. Use `whoami` to confirm which account the stored credential belongs to before sending paid research work.
API-backed research requests use the Vidbyte account's usage balance. The CLI's local runtime admission also uses that account balance by default, while model usage remains billed to your own provider account.
Shell
Vidbyte account login
vidbyte-cli login
vidbyte-cli whoami3: Check local runtime prerequisites
The base installation is enough for hosted research. Install the optional Codex extra only when you need local runtime primitives, then run the doctor and catalog commands before any paid admission. These checks confirm the local host and show the runtime capabilities visible to the CLI.
Shell
Optional local runtime setup
python -m pip install "vidbyte-cli[codex]"
vidbyte-cli runtime doctor
vidbyte-cli runtime list4: Connect the provider used by local execution
The current persistence and task-board runtimes use an OpenAI provider credential. Run provider login to enter it through a hidden prompt, then use provider whoami to verify the stored credential. Provider keys are separate from the Vidbyte API key and are never sent in a runtime admission request.
The Credentials page covers all provider identifiers accepted by the CLI, including the stdin and restricted-file options for scripts and machines without an OS keyring.
Shell
OpenAI provider setup
vidbyte-cli provider login openai
vidbyte-cli provider whoami openai5. Run the first commands
Once the checks pass, choose a hosted research workflow or a local runtime. Starting, adding, and resuming research runs are priced and idempotent. A caller-chosen idempotency key is for recovering an admission whose result was not seen; reusing it does not resume local work or deduplicate a runtime board.
Shell
Common CLI workflows
# Hosted research
vidbyte-cli research start "Compare spaced repetition with retrieval practice"
vidbyte-cli research threads
vidbyte-cli research status <run_id>
vidbyte-cli research watch <run_id>
# Machine-readable output and profile isolation
vidbyte-cli --format json research threads
vidbyte-cli --profile work research threads
# Local task board: each argument is one ordered task
vidbyte-cli runtime task-board "Inspect the repository" "Summarize the risks" --window 1
# One persistent Codex session
vidbyte-cli runtime persistence "Review this repository and fix the failing test" --strength 1