Skip to main content
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
Or download from GitHub Releases, or build from source: 
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

​
Agents

Manage agent identities and their access to secrets. 
onecli agents list                                     # List all agents
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
onecli agents secrets --id X                           # List assigned secrets
onecli agents set-secrets --id X --secret-ids a,b      # Set assigned secrets (auto-switches to selective mode)
onecli agents set-secret-mode --id X --mode selective  # Set secret mode

​
Secrets

Manage credentials stored in the vault. 
onecli secrets list                                    # List all secrets
onecli secrets create --name X --type anthropic ...    # Create a new secret
onecli secrets update --id X --value Y                 # Update a secret
onecli secrets delete --id X                           # Delete a secret

​
Rules

Manage policy rules that control what agents can access. See the Rules guide for details on how rules work. 
onecli rules list                                      # List all policy rules
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
When creating or updating a rule, the available flags are:
FlagDescription
--nameDisplay name for the rule
--host-patternHost to match (e.g. api.anthropic.com)
--path-patternURL path to match (e.g. /v1/*)
--methodHTTP method: GET, POST, PUT, PATCH, DELETE
--actionblock or rate_limit
--agent-idScope to a specific agent (omit for all agents)
--rate-limitMax requests per window (required for rate_limit)
--rate-limit-windowTime window: minute, hour, or day
--enabledEnable or disable the rule (default: true)
--jsonRaw JSON payload (overrides individual flags)
--dry-runValidate 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
Authentication is only required when the server enforces it. In local/single-user mode, commands work without logging in.

​
Config

Read and write configuration values. 
onecli config get <key>                                # Read config value
onecli config set <key> <value>                        # Write config value

​
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,secretMode
# [{"id": "agent_abc123", "name": "My Agent", "secretMode": "all"}, ...]
Agents and scripts can parse responses directly without jq or string manipulation.

​
Environment variables

VariableDescription
ONECLI_API_KEYAPI key (overrides stored key)
ONECLI_API_HOSTAPI base URL (default: https://app.onecli.sh)
ONECLI_ENVdev or production

​
Example: agent orchestrator bootstrapping

A common pattern is an orchestrator that provisions agents before they start working: 
# Create the agent
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)

# Assign only the secrets it needs (automatically switches to selective mode)
onecli agents set-secrets --id "$AGENT" --secret-ids "$GMAIL_SECRET_ID"

# Pass the token to the agent container
docker run -e HTTPS_PROXY=http://onecli:10255 \
  -e PROXY_AUTH="$TOKEN" \
  my-email-agent:latest
The agent starts with scoped access to only Gmail, enforced by the vault and any rules you’ve configured. No hardcoded keys, no broad access.