> ## 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. # CLI Reference: Commands, Flags & Configuration > Full reference for the OneCLI command-line tool: installation, every command with flags, environment variables, and configuration. 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](https://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 ```bash theme={null} curl -fsSL onecli.sh/cli/install | sh ``` Or download from [GitHub Releases](https://github.com/onecli/onecli-cli/releases), or build from source: ```bash theme={null} go install github.com/onecli/onecli-cli/cmd/onecli@latest ``` ## Quick start ```bash theme={null} 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](/guides/coding-agents) for the full walkthrough. ```bash theme={null} 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](/guides/projects) for details. ```bash theme={null} onecli projects list # List all projects onecli projects get --id X # Get a single project onecli projects create --name "payments-app" # Create a new project onecli projects rename --id X --name "new-name" # Rename a project onecli projects delete --id X --confirm # Delete a project ``` Deleting a project permanently removes all its agents, secrets, connections, rules, and audit logs. The `--confirm` flag is required to prevent accidental deletion. You cannot delete your last remaining project. Most commands accept `--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. ```bash theme={null} 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. ```bash theme={null} onecli secrets list # List secrets in active project onecli secrets list --project payments-app # List secrets in a specific project onecli secrets create --name "Anthropic" --type anthropic \ --value "$ANTHROPIC_API_KEY" \ --host-pattern api.anthropic.com # Anthropic API key onecli secrets create --name "OpenAI" --type openai \ --value "$OPENAI_API_KEY" \ --host-pattern api.openai.com # OpenAI API key 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 ``` The `--type` flag accepts `anthropic`, `openai`, or `generic`. For `anthropic` and `openai` types, the gateway handles header injection automatically. For `generic` secrets, you must specify injection flags. When creating or updating a generic secret, the available injection flags are: | 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](/guides/credential-stubs/gmail) URL your MCP server needs to start. ```bash theme={null} 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](/guides/rules) for details on how rules work. ```bash theme={null} 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 ``` When creating or updating a rule, the available flags are: | 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 | ### Organization Organization-scoped commands manage resources that apply across all projects. These mirror the project-level `secrets`, `rules`, and `apps` commands but operate at the org level — no `--project` flag needed. #### Org Secrets ```bash theme={null} onecli org secrets list # List all org-scoped secrets onecli org secrets create --name "Anthropic" --type anthropic \ --value "$ANTHROPIC_API_KEY" \ --host-pattern api.anthropic.com # Create org secret onecli org secrets update --id X --value Y # Update an org secret onecli org secrets delete --id X # Delete an org secret ``` Org secrets use the same `--type`, injection flags (`--header-name`, `--param-name`, etc.), and `--json` override as project-level secrets. #### Org Rules ```bash theme={null} onecli org rules list # List all org-scoped rules onecli org rules get --id X # Get a single org rule onecli org rules create --name X --host-pattern Y \ --action block # Create org rule onecli org rules update --id X --enabled false # Update an org rule onecli org rules delete --id X # Delete an org rule ``` Org rules use the same flags as project-level rules (`--host-pattern`, `--action`, `--rate-limit`, etc.). #### Org Permissions Manage granular tool-level permissions for app providers at the org level. ```bash theme={null} onecli org rules permissions get --provider github # Get tool permissions for a provider onecli org rules permissions set --provider github \ --json '{"changes": [{"toolId": "repos.create", "permission": "allow"}]}' ``` Each permission change specifies a `toolId` and a `permission` value: `allow`, `manual_approval`, or `block`. #### Org Connections ```bash theme={null} onecli org connections list # List all org connections onecli org connections list --provider github # Filter by provider onecli org connections delete --id X # Delete a connection ``` #### Org Apps Manage BYOC (bring your own credentials) app configuration at the org level. ```bash theme={null} onecli org apps configured # List providers with org credentials onecli org apps get --provider gmail # Get config status for a provider onecli org apps configure --provider gmail \ --client-id X --client-secret Y # Save BYOC credentials onecli org apps remove --provider gmail # Remove BYOC credentials onecli org apps toggle --provider gmail --enabled true # Enable or disable an app ``` ### Auth Authenticate with the OneCLI server. ```bash theme={null} 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. ```bash theme={null} onecli config get # Read config value onecli config set # 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: ```bash theme={null} 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"}, ...] ``` Agents and scripts can parse responses directly without `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: ```bash theme={null} # 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 ``` The agent sees only the secrets in its project, enforced by the gateway and any [rules](/guides/rules) you've configured. No hardcoded keys, no broad access.