Using the CLI

The opub CLI is open source. It connects a browser-provisioned compute key to a supported agent and links sessions to the project, so donors can see that donated compute is being actively used on it.

The CLI is optional. A compute key is an OpenRouter-compatible API key funded by donated compute. Each key has a dollar limit set by the maintainer. Use it with any compatible tool or workflow; sessions just won't be linked if you use the key directly.

The normal path is:

1. Install opub.
2. Run opub setup <target> once for the agent you use.
3. Start work with opub run <target> when you want a linked funded session.

For a narrative walkthrough, see The opub CLI puts donated compute in your terminal. For help choosing a target, see Supported agents.

Install

curl -fsSL https://opub.dev/install.sh | sh

The installer downloads signed-and-checksummed release archives. Pin a version with OPUB_VERSION=v0.1.0.

Setup

From inside the repository you maintain, run setup for one target. The setup command contains non-secret project and compute key IDs only; after it starts, opub setup prompts for the one-time provider key shown in the browser.

For example:

opub setup codex --project owner/repo --compute-key-id ck_...

opub setup verifies the repository origin matches --project, prompts for the one-time provider key, stores that provider secret in your system credential store, and writes non-secret config for the agent. The provider secret does not appear in the shell command or config files.

Run

Use opub run <target> when you want the work to use donated compute and carry local session context.

Start an interactive agent:

opub run claude
opub run codex
opub run copilot
opub run vibe
opub run opencode

Pass a task through to the agent:

opub run codex -- "fix the failing test"
opub run copilot -- suggest "triage the oldest open issue"
opub run claude -- "audit this patch for security risks"

Run Continue headlessly:

opub run continue -- -p "Review staged changes for obvious bugs" --silent

Continue sessions require the Continue CLI (cn) on your PATH. See the Continue CLI guide for install instructions.

opub run creates or refreshes a local work session, injects provider credentials and runtime launch proof into the agent process, and loads the bundled skill, plugin, or generated agent config. The agent itself is unchanged — opub wraps the launch.

Check your setup

opub doctor codex

opub doctor reports repo root, config paths, credential presence, agent executable, session state, and MCP status. Run it if setup or a session behaves unexpectedly.

What the session signal means

When you run an agent through opub run, the CLI reads your provider key from the OS system keyring and injects it into the agent's environment. A local MCP server starts alongside the agent, exposing four tools: identify_project, get_compute_status, get_active_work_session, and finish_work_session. Each tool returns project and session metadata — the repository, compute key, target agent, and session timestamps. None return the provider key, and none observe prompts, responses, files, diffs, commits, pull requests, or issues.

A skill file, plugin, or generated config rule instructs the agent to call identify_project at session start and surface the project context. The instruction cannot expand to request sensitive data — the MCP server simply does not have it.

Spend attribution works through the provider's own API ledger: OpenRouter sees your compute key in every request and links token spend to that key. The local MCP server plays no role in spend tracking. opub does not observe your prompts or responses.

If you use the key directly without opub run, spend still accrues to the project. The local session link will not be present, but everything else works the same.