Skip to main content
onecli run wraps a coding agent process with OneCLI gateway access. Your agent’s HTTPS traffic routes through the gateway, which injects stored credentials automatically. The agent never sees raw API keys or OAuth tokens.

​
Supported agents

Any command works after --. The agents listed above also get an auto-installed skill file that teaches them how to use the gateway.

​
Setup

1

Start OneCLI

2

Install the CLI

Get your API key from the dashboard at localhost:10254.
3

Launch your agent

You’ll see onecli: gateway connected. Starting claude... and your agent starts with the gateway configured.

​
What onecli run does

When you run onecli run -- claude, the CLI:
  1. Fetches gateway configuration from the OneCLI server
  2. Writes a CA bundle (your system CAs plus the gateway CA) to ~/.onecli/ca-bundle.pem
  3. Installs the OneCLI gateway skill into the agent’s skill directory (for Claude Code, ~/.claude/skills/onecli-gateway/SKILL.md), fetched from the server with a built-in fallback
  4. Injects HTTPS_PROXY, the CA trust variables (SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, and friends), and ONECLI_GATEWAY=true into the child process
  5. Hands over terminal control to the agent
The skill file is refreshed on every launch. Standard HTTP clients (curl, fetch, requests, axios, Go net/http, git) pick up the proxy settings automatically.

​
Choosing the agent identity

Each onecli run session acts as one agent from your project, which decides the credentials the gateway injects and the rules that apply. The identity resolves in this order:
  1. --agent <identifier> flag
  2. ONECLI_AGENT environment variable
  3. onecli config set agent <identifier> (requires CLI 2.10+)
  4. The project’s default agent
Pin a machine once and forget it:
The pin is local to the machine. It doesn’t change the project’s default agent, so your teammates’ plain onecli run is unaffected. The dashboard’s Install page generates a setup command with the pin included when you pick a non-default agent.

​
How agents connect to services

The skill file teaches supported agents a simple workflow:
  1. Make the request directly. The agent calls the real API URL (e.g. https://gmail.googleapis.com/...). No auth headers needed. If credentials are configured, the gateway injects them and the request succeeds.
  2. If it fails, help the user connect. The gateway returns a structured error with a connect_url, and the agent presents that link to the user.
  3. Poll and retry. The agent polls the connection status and retries automatically once the user connects the service. No manual “try now” needed.
For OAuth apps (Gmail, GitHub, Google Drive, and 13 others), the user connects with one click in the dashboard. For API key services (Stripe, custom APIs), the user adds a secret via the dashboard or onecli secrets create.

​
Flags

​
Dry run

Use --dry-run to inspect what onecli run would do without side effects:
This prints the resolved binary path, injected environment variable keys, and CA cert path as JSON.

​
Compared to the SDK path

onecli run is for coding agents running directly on your machine. If your agents run in Docker containers (e.g. via NanoClaw), use the Node.js SDK instead. Both paths use the same gateway, the same secrets, and the same policy rules.