Documentation Index
Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt
Use this file to discover all available pages before exploring further.
The onecli CLI lets you manage your OneCLI instance from the terminal. Create agents, add secrets, configure access, all with JSON output that AI agents can parse and act on.
GitHub: github.com/onecli/onecli-cli
Why a CLI for managing OneCLI?
The dashboard is great for humans. But when an AI agent needs to set up its own environment (create its identity, register the secrets it needs, check its current access), it shouldn’t need a human clicking through a UI.
The onecli CLI gives agents (and the frameworks that orchestrate them) a programmatic interface to manage the OneCLI server. An agent orchestrator can spin up a new agent, assign it credentials for specific services, and configure rules, all in a single script, no browser required.
This is especially useful for:
- Agent bootstrapping, where an orchestrator creates an agent identity and assigns secrets before the agent starts working
- Dynamic provisioning: spin up short-lived agents with scoped access for specific tasks, then clean up after
- CI/CD pipelines that automate agent and secret management as part of your deployment
- Self-healing agents that detect a missing credential, check their own status, and request what they need
Install
curl -fsSL onecli.sh/cli/install | sh
go install github.com/onecli/onecli-cli/cmd/onecli@latest
Quick start
onecli auth login --api-key oc_...
onecli agents list
onecli secrets list
onecli agents create --name "My Agent" --identifier my-agent
Commands
Run
Wrap a coding agent process with OneCLI gateway access. See the Coding Agents guide for the full walkthrough.
onecli run -- claude # Launch Claude Code with gateway access
onecli run --agent my-agent -- cursor # Use a specific agent identity
onecli run --project payments-app -- claude # Use agent from a specific project
onecli run --dry-run -- claude # Preview config without launching
onecli run --gateway localhost:10255 -- claude # Override gateway address
onecli run --no-ca -- claude # Skip CA cert injection
Projects
Manage projects (isolated workspaces for agents, secrets, and rules). See the Projects guide for details.
onecli projects list # List all projects
onecli projects create --name "payments-app" # Create a new project
onecli projects delete --id X # Delete a project
--project (or -p) to target a specific project. Without it, the active project from onecli config set project is used, or the default project.
Agents
Manage agent identities. Agents belong to a project and see all secrets in that project.
onecli agents list # List agents in active project
onecli agents list --project payments-app # List agents in a specific project
onecli agents get-default # Get the default agent
onecli agents create --name X --identifier Y # Create a new agent
onecli agents delete --id X # Delete an agent
onecli agents rename --id X --name Y # Rename an agent
onecli agents regenerate-token --id X # Regenerate access token
Secrets
Manage credentials stored in the vault.
onecli secrets list # List secrets in active project
onecli secrets list --project payments-app # List secrets in a specific project
onecli secrets create --name X --type generic \
--value Y --host-pattern api.example.com \
--header-name Authorization \
--value-format "Bearer {value}" # Header injection
onecli secrets create --name X --type generic \
--value Y --host-pattern api.example.com \
--param-name key # Query param injection
onecli secrets update --id X --value Y # Update a secret
onecli secrets delete --id X # Delete a secret
| Flag | Description |
|---|
--header-name | Inject as an HTTP header (e.g. Authorization) |
--value-format | Header value template (default: {value}, e.g. Bearer {value}) |
--param-name | Inject as a URL query parameter (e.g. key) |
--param-format | Param value template (default: {value}) |
--header-name and --param-name are mutually exclusive: each secret injects as either a header or a query parameter, not both.
Apps
Manage OAuth app connections so the OneCLI gateway can handle token exchange on behalf of agents. After configuring an app, use apps list to get the credential stubs docs URL your MCP server needs to start.
onecli apps list # List all apps with config and connection status
onecli apps get --provider gmail # Get a single app with setup guidance
onecli apps configure --provider gmail --client-id X \
--client-secret Y # Save OAuth credentials (BYOC)
onecli apps remove --provider gmail # Remove OAuth credentials
onecli apps disconnect --provider gmail # Disconnect an app connection
Rules
Manage policy rules that control what agents can access. See the Rules guide for details on how rules work.
onecli rules list # List rules in active project
onecli rules list --project payments-app # List rules in a specific project
onecli rules get --id X # Get a single rule
onecli rules create --name X --host-pattern Y ... # Create a new rule
onecli rules update --id X [--action block] ... # Update a rule
onecli rules delete --id X # Delete a rule
| Flag | Description |
|---|
--name | Display name for the rule |
--host-pattern | Host to match (e.g. api.anthropic.com) |
--path-pattern | URL path to match (e.g. /v1/*) |
--method | HTTP method: GET, POST, PUT, PATCH, DELETE |
--action | block or rate_limit |
--agent-id | Scope to a specific agent (omit for all agents) |
--rate-limit | Max requests per window (required for rate_limit) |
--rate-limit-window | Time window: minute, hour, or day |
--enabled | Enable or disable the rule (default: true) |
--json | Raw JSON payload (overrides individual flags) |
--dry-run | Validate without executing |
Auth
Authenticate with the OneCLI server.
onecli auth login [--api-key oc_...] # Store API key
onecli auth logout # Remove stored API key
onecli auth status # Check current auth state
onecli auth api-key # Show your current API key
onecli auth regenerate-api-key # Regenerate your API key
Config
Read and write configuration values.
onecli config get <key> # Read config value
onecli config set <key> <value> # Write config value
onecli config set project payments-app # Set active project for all commands
Output
All output is JSON. Use --fields to select specific fields, or --quiet to extract a single value:
onecli agents list --quiet id
# "agent_abc123"
# "agent_def456"
onecli agents list --fields id,name,identifier
# [{"id": "agent_abc123", "name": "My Agent", "identifier": "my-agent"}, ...]
jq or string manipulation.
Environment variables
| Variable | Description |
|---|
ONECLI_API_KEY | API key (overrides stored key) |
ONECLI_API_HOST | API base URL (default: https://app.onecli.sh) |
ONECLI_ENV | dev or production |
Example: agent orchestrator bootstrapping
A common pattern is an orchestrator that provisions agents before they start working:
# Create a project for this workflow
onecli projects create --name "email-workflow"
onecli config set project email-workflow
# Add the secret the agent needs
onecli secrets create --name "Gmail" --type generic \
--value "$GMAIL_KEY" --host-pattern "*.googleapis.com" \
--header-name Authorization --value-format "Bearer {value}"
# Create the agent (it sees all secrets in the project)
AGENT=$(onecli agents create --name "email-agent" --identifier email-agent --quiet id)
# Get its access token
TOKEN=$(onecli agents regenerate-token --id "$AGENT" --quiet accessToken)
# Pass the token to the agent container
docker run -e HTTPS_PROXY=http://onecli:10255 \
-e PROXY_AUTH="$TOKEN" \
my-email-agent:latest
