OneCLI

https://www.onecli.sh/docs
Admin
OneCLI is an open-source credential and policy layer for AI agents that securely manages secrets...
Tokens:9,778
Snippets:103
Trust Score:3.8
Update:6 months ago
Show doc for...
Tokens:
Raw
### Agent Orchestrator Bootstrapping Example

Source: https://www.onecli.sh/docs/cli/onecli-cli

An example script demonstrating a common pattern where an orchestrator provisions agents before they start working. It covers creating an agent, obtaining its access token, assigning secrets, and running the agent in a Docker container.

```bash
# 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
```

--------------------------------

### Install OneCLI Go SDK

Source: https://www.onecli.sh/docs/sdks/go

This command installs the official Go SDK for OneCLI. It is a prerequisite for using the SDK in your Go applications.

```bash
go get github.com/onecli/go-sdk
```

--------------------------------

### Quick Start OneCLI CLI

Source: https://www.onecli.sh/docs/cli/onecli-cli

Basic commands to authenticate, list resources, and create a new agent identity.

```bash
onecli auth login --api-key oc_...
onecli agents list
onecli secrets list
onecli agents create --name "My Agent" --identifier my-agent
```

--------------------------------

### Install OneCLI CLI

Source: https://www.onecli.sh/docs/cli/onecli-cli

Methods to install the OneCLI CLI tool, either via a shell script or by building from source using Go.

```bash
curl -fsSL onecli.sh/cli/install | sh
```

```bash
go install github.com/onecli/onecli-cli/cmd/onecli@latest
```

--------------------------------

### Install OneCLI SDK

Source: https://www.onecli.sh/docs/sdks/node

Commands to install the @onecli-sh/sdk package using common Node.js package managers.

```bash
npm install @onecli-sh/sdk
```

```bash
pnpm add @onecli-sh/sdk
```

```bash
yarn add @onecli-sh/sdk
```

--------------------------------

### Install OneCLI Ruby SDK

Source: https://www.onecli.sh/docs/sdks/ruby

Command to install the OneCLI Ruby gem using the RubyGems package manager.

```bash
gem install onecli
```

--------------------------------

### Java SDK Usage Example

Source: https://www.onecli.sh/docs/sdks/java

This Java code demonstrates how to initialize the OneCLI SDK, retrieve container configuration, and print environment variables and mounts. It assumes the OneCLI proxy is running on http://localhost:18080.

```java
import sh.onecli.OneCLI;

OneCLI oc = new OneCLI("http://localhost:18080");

ContainerConfig config = oc.getContainerConfig();
System.out.println(config.getEnv());
System.out.println(config.getMounts());
```

--------------------------------

### Install OneCLI Python SDK

Source: https://www.onecli.sh/docs/sdks/python

This snippet shows the command to install the OneCLI Python SDK using pip. It's a prerequisite for using the SDK in your Python applications.

```bash
pip install onecli
```

--------------------------------

### Install OneCLI .NET SDK

Source: https://www.onecli.sh/docs/sdks/dotnet

The command to add the OneCLI SDK package to your .NET project using the dotnet CLI.

```bash
dotnet add package OneCLI.Sdk
```

--------------------------------

### Start OneCLI with Docker

Source: https://www.onecli.sh/docs/quickstart

Runs the OneCLI container with the web dashboard and gateway exposed, using a named volume for persistent storage.

```bash
docker run --pull always -p 10254:10254 -p 10255:10255 -v onecli-data:/app/data ghcr.io/onecli/onecli
```

--------------------------------

### Deploy OneCLI with Docker Compose

Source: https://www.onecli.sh/docs/quickstart

Clones the repository and starts the OneCLI service stack using Docker Compose.

```bash
git clone https://github.com/onecli/onecli.git
cd onecli/docker
docker compose up
```

--------------------------------

### Usage: Get Container Configuration with OneCLI Go SDK

Source: https://www.onecli.sh/docs/sdks/go

This Go code snippet demonstrates how to initialize the OneCLI SDK, retrieve Docker container configuration, and print environment variables and mounts. It requires the OneCLI proxy to be running locally.

```go
package main

import (
    "fmt"
    onecli "github.com/onecli/go-sdk"
)

func main() {
    oc := onecli.New("http://localhost:18080")

    config, err := oc.GetContainerConfig()
    if err != nil {
        panic(err)
    }

    fmt.Println(config.Env)
    fmt.Println(config.Mounts)
}
```

--------------------------------

### Integrate OneCLI with Node.js SDK

Source: https://www.onecli.sh/docs/quickstart

Installs the OneCLI SDK and demonstrates how to use the applyContainerConfig method to automatically inject proxy and volume configurations into container arguments.

```bash
npm install @onecli-sh/sdk
```

```typescript
import { OneCLI } from "@onecli-sh/sdk";

const onecli = new OneCLI({
  url: "http://localhost:10254",
  apiKey: "oc_your_api_key",
});

const args = ["run", "-i", "--rm", "--name", "my-agent"];

const active = await onecli.applyContainerConfig(args);
```

--------------------------------

### Install OneCLI Rust SDK

Source: https://www.onecli.sh/docs/sdks/rust

Add the OneCLI dependency to your Cargo.toml file to enable the SDK in your Rust project.

```toml
[dependencies]
onecli = "0.1"
```

--------------------------------

### OneCLI CLI: Manage Agents and Credentials

Source: https://www.onecli.sh/docs/guides/nanoclaw

These bash commands demonstrate how to install the OneCLI CLI, create agent identities, add secrets (like API tokens), and assign these secrets to specific agents. This automation is crucial for dynamic agent provisioning with NanoClaw.

```bash
# Install the CLI
curl -fsSL onecli.sh/cli/install | sh

# Create an agent for each NanoClaw agent
onecli agents create --name "email-agent" --identifier email-agent

# Add credentials
onecli secrets create --name "Gmail" --type google --value "$GMAIL_TOKEN"

# Assign specific secrets to the agent
AGENT_ID=$(onecli agents list --quiet id | head -1)
onecli agents set-secrets --id "$AGENT_ID" --secret-ids "$SECRET_ID"
onecli agents set-secret-mode --id "$AGENT_ID" --mode selective
```

--------------------------------

### Start Bitwarden Agent Access Listener

Source: https://www.onecli.sh/docs/vaults/bitwarden

Initializes the Bitwarden Agent Access CLI listener to generate a pairing code for the OneCLI gateway.

```bash
aac listen --psk
```

--------------------------------

### GET /api/container-config

Source: https://www.onecli.sh/docs/sdks/node

Fetches the raw container configuration required for routing traffic through the OneCLI gateway.

```APIDOC
## GET /api/container-config

### Description
Retrieves the environment variables, CA certificate, and path information necessary to configure a container for OneCLI proxying.

### Method
GET

### Endpoint
/api/container-config

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token using the API key.

### Request Example
GET /api/container-config
Authorization: Bearer oc_your_api_key

### Response
#### Success Response (200)
- **env** (object) - Key-value pairs of proxy environment variables (e.g., HTTPS_PROXY, HTTP_PROXY).
- **caCertificate** (string) - PEM-formatted CA certificate content.
- **caCertificateContainerPath** (string) - The target file path for the CA certificate inside the container.

#### Response Example
{
  "env": {
    "HTTPS_PROXY": "http://proxy.onecli.sh:8080",
    "HTTP_PROXY": "http://proxy.onecli.sh:8080"
  },
  "caCertificate": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----",
  "caCertificateContainerPath": "/tmp/onecli-proxy-ca.pem"
}
```

--------------------------------

### Run OneCLI Docker Container

Source: https://www.onecli.sh/docs/guides/nanoclaw

This command starts the OneCLI Docker container, exposing necessary ports and mounting a volume for persistent data. It's a prerequisite for integrating OneCLI with NanoClaw.

```bash
docker run --pull always \
  -p 10254:10254 \
  -p 10255:10255 \
  -v onecli-data:/app/data \
  ghcr.io/onecli/onecli
```

--------------------------------

### Use OneCLI Python SDK for Container Configuration

Source: https://www.onecli.sh/docs/sdks/python

This snippet demonstrates how to use the OneCLI Python SDK to get container configuration. It initializes the OneCLI client and retrieves environment variables and mount points for a container.

```python
from onecli import OneCLI

oc = OneCLI(onecli_url="http://localhost:18080")

# Get container configuration
config = oc.get_container_config()
print(config.env)
print(config.mounts)
```

--------------------------------

### Handle OneCLI SDK Errors

Source: https://www.onecli.sh/docs/sdks/node

Example of catching and handling errors specific to the OneCLI SDK, such as missing credentials or connectivity issues.

```typescript
import { OneCLIError } from "@onecli-sh/sdk";

try {
  const onecli = new OneCLI();
  await onecli.getContainerConfig();
} catch (error) {
  if (error instanceof OneCLIError) {
    console.error(error.message);
  }
}
```

--------------------------------

### Java/Kotlin SDK Installation Dependency

Source: https://www.onecli.sh/docs/sdks/java

This XML snippet shows the Maven dependency required to include the OneCLI Java SDK in your project. It specifies the group ID, artifact ID, and version.

```xml
<dependency>
  <groupId>sh.onecli</groupId>
  <artifactId>sdk</artifactId>
  <version>0.1.0</version>
</dependency>
```

--------------------------------

### Initialize and Use OneCLI Client

Source: https://www.onecli.sh/docs/sdks/ruby

Demonstrates how to initialize the OneCLI client and retrieve Docker container configurations such as environment variables and mounts.

```ruby
require "onecli"

oc = OneCLI::Client.new(onecli_url: "http://localhost:18080")

config = oc.get_container_config
puts config.env
puts config.mounts
```

--------------------------------

### Fetch Docker Container Configuration

Source: https://www.onecli.sh/docs/sdks/rust

Demonstrates how to initialize the OneCLI client and retrieve container configuration details such as environment variables and mounts.

```rust
use onecli::OneCLI;

#[tokio::main]
async fn main() {
    let oc = OneCLI::new("http://localhost:18080");

    let config = oc.get_container_config().await.unwrap();
    println!("{:?}", config.env);
    println!("{:?}", config.mounts);
}
```

--------------------------------

### Configure OneCLI Client in .NET

Source: https://www.onecli.sh/docs/sdks/dotnet

Demonstrates how to initialize the OneCLI client and retrieve container configuration settings. This requires an active OneCLI proxy instance running at the specified endpoint.

```csharp
using OneCLI;

var oc = new OneCLIClient("http://localhost:18080");

var config = await oc.GetContainerConfigAsync();
Console.WriteLine(config.Env);
Console.WriteLine(config.Mounts);
```

--------------------------------

### Initialize and Apply Container Configuration

Source: https://www.onecli.sh/docs/sdks/node

Demonstrates how to initialize the OneCLI client and apply proxy configurations to a Docker argument array. This process automatically injects environment variables and volume mounts required for secure communication.

```typescript
import { OneCLI } from "@onecli-sh/sdk";

const onecli = new OneCLI({
  url: "http://localhost:10254",
  apiKey: "oc_your_api_key",
});

const args = ["run", "-i", "--rm", "--name", "my-agent"];
const active = await onecli.applyContainerConfig(args);
console.log(active);
```

--------------------------------

### Configure via Environment Variables

Source: https://www.onecli.sh/docs/sdks/node

Shows how to configure the OneCLI client using environment variables instead of explicit constructor arguments.

```bash
export ONECLI_URL=http://localhost:10254
export ONECLI_API_KEY=oc_your_api_key
```

```typescript
import { OneCLI } from "@onecli-sh/sdk";

const onecli = new OneCLI();
const active = await onecli.applyContainerConfig(args);
```

--------------------------------

### Fetching Documentation Index

Source: https://www.onecli.sh/docs/guides/rules

Retrieves the complete documentation index to discover available pages.

```APIDOC
## GET /docs/index

### Description
Fetches the complete documentation index.

### Method
GET

### Endpoint
/docs/index

### Response
#### Success Response (200 OK)
- **index_url** (string) - URL to the documentation index file.

#### Response Example
```json
{
  "index_url": "https://onecli.sh/docs/llms.txt"
}
```
```

--------------------------------

### OneCLI Configuration Management

Source: https://www.onecli.sh/docs/cli/onecli-cli

Commands for reading and writing configuration values for OneCLI. These commands allow users to manage settings directly from the command line.

```bash
onecli config get <key>                                # Read config value
onecli config set <key> <value>                        # Write config value
```

--------------------------------

### OneCLI Output Formatting

Source: https://www.onecli.sh/docs/cli/onecli-cli

Demonstrates how to control the output format of OneCLI commands using `--fields` for specific data selection and `--quiet` for extracting single values. This enables direct parsing of responses by scripts.

```bash
onecli agents list --quiet id
# "agent_abc123"
# "agent_def456"

onecli agents list --fields id,name,secretMode
# [{"id": "agent_abc123", "name": "My Agent", "secretMode": "all"}, ...]
```

--------------------------------

### Apply Container Configuration with Node.js SDK

Source: https://www.onecli.sh/docs/guides/nanoclaw

This TypeScript code snippet demonstrates how to use the OneCLI Node.js SDK to automatically configure NanoClaw agent containers. It sets up the HTTP_PROXY, HTTPS_PROXY, and mounts necessary CA certificates by calling the `applyContainerConfig` method. The SDK handles the complexities of proxy configuration and security.

```typescript
import { OneCLI } from "@onecli-sh/sdk";

const onecli = new OneCLI({
  url: "http://localhost:10254",
  apiKey: "oc_agent_access_token",
});

const args = ["run", "-i", "--rm", "--name", "my-nanoclaw-agent"];
await onecli.applyContainerConfig(args);

// args now has HTTPS_PROXY, CA certs, and volume mounts configured
```

--------------------------------

### Import OneCLI SDK Types in TypeScript

Source: https://www.onecli.sh/docs/sdks/node

Shows how to import various types from the `@onecli-sh/sdk` package, including options for OneCLI, container configuration, and applying container configurations. These types are essential for strongly-typed development with the SDK.

```typescript
import type {
  OneCLIOptions,
  ContainerConfig,
  ApplyContainerConfigOptions,
} from "@onecli-sh/sdk";
```

--------------------------------

### OneCLI Authentication Commands

Source: https://www.onecli.sh/docs/cli/onecli-cli

Commands for managing authentication with the OneCLI server, including logging in, logging out, checking status, and managing API keys. Authentication is optional in local/single-user modes.

```bash
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
```

--------------------------------

### Configure Host Proxy Environment Variables

Source: https://www.onecli.sh/docs/quickstart

Sets the proxy environment variables on the host machine to route traffic through the OneCLI gateway.

```bash
export HTTP_PROXY=http://localhost:10255
export HTTPS_PROXY=http://localhost:10255
```

--------------------------------

### Creating a New Rule - Action Configuration

Source: https://www.onecli.sh/docs/guides/rules

Defines the action to take when a request matches the rule's endpoint criteria.

```APIDOC
## POST /api/rules/{rule_id}/action

### Description
Configures the action for a specific rule.

### Method
POST

### Endpoint
/api/rules/{rule_id}/action

### Parameters
#### Path Parameters
- **rule_id** (string) - Required - The ID of the rule to configure.

#### Request Body
- **action_type** (string) - Required - The type of action: `Block` or `Rate Limit`.
- **rate_limit_options** (object) - Optional - Required if `action_type` is `Rate Limit`.
  - **request_count** (integer) - Required - How many requests to allow.
  - **time_window** (string) - Required - The period over which the count resets (`minute`, `hour`, `day`).

### Request Example (Block Action)
```json
{
  "action_type": "Block"
}
```

### Request Example (Rate Limit Action)
```json
{
  "action_type": "Rate Limit",
  "rate_limit_options": {
    "request_count": 20,
    "time_window": "hour"
  }
}
```

### Response
#### Success Response (200 OK)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Action configured successfully for rule rule_123abc"
}
```
```

--------------------------------

### Creating a New Rule - Endpoint Configuration

Source: https://www.onecli.sh/docs/guides/rules

Defines the specific requests a rule applies to, including host, path, method, and agent scope.

```APIDOC
## POST /api/rules

### Description
Creates a new rule to control agent access.

### Method
POST

### Endpoint
/api/rules

### Parameters
#### Request Body
- **name** (string) - Required - A human-readable label for the rule.
- **host_pattern** (string) - Required - The API hostname to match. Use `*.example.com` for wildcard subdomains.
- **path_pattern** (string) - Optional - The URL path to match. Use `/path/*` for prefix matching.
- **method** (string) - Required - The HTTP method to match: GET, POST, PUT, PATCH, DELETE, or any.
- **scope** (string) - Required - Which agents this rule applies to: a specific agent or all agents.

### Request Example
```json
{
  "name": "Block Gmail deletes",
  "host_pattern": "gmail.googleapis.com",
  "path_pattern": "/gmail/v1/users/*/messages/*",
  "method": "DELETE",
  "scope": "All agents"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the created rule.
- **name** (string) - The name of the rule.
- **host_pattern** (string) - The host pattern configured for the rule.
- **path_pattern** (string) - The path pattern configured for the rule.
- **method** (string) - The HTTP method configured for the rule.
- **scope** (string) - The scope of the rule.

#### Response Example
```json
{
  "id": "rule_123abc",
  "name": "Block Gmail deletes",
  "host_pattern": "gmail.googleapis.com",
  "path_pattern": "/gmail/v1/users/*/messages/*",
  "method": "DELETE",
  "scope": "All agents"
}
```
```

--------------------------------

### Manage Rules via OneCLI

Source: https://www.onecli.sh/docs/cli/onecli-cli

Commands for managing policy rules that control agent access to specific hosts, paths, and HTTP methods.

```bash
onecli rules list
onecli rules get --id X
onecli rules create --name X --host-pattern Y ...
onecli rules update --id X [--action block] ...
onecli rules delete --id X
```

--------------------------------

### Fetch Raw Container Configuration

Source: https://www.onecli.sh/docs/sdks/node

Retrieves the raw configuration object from the OneCLI gateway, including environment variables and CA certificate paths.

```typescript
const config = await onecli.getContainerConfig();
console.log(config.env);
console.log(config.caCertificate);
console.log(config.caCertificateContainerPath);
```

--------------------------------

### Manage Agents via OneCLI

Source: https://www.onecli.sh/docs/cli/onecli-cli

Commands for managing agent identities, including listing, creating, deleting, and configuring secret access.

```bash
onecli agents list
onecli agents get-default
onecli agents create --name X --identifier Y
onecli agents delete --id X
onecli agents rename --id X --name Y
onecli agents regenerate-token --id X
onecli agents secrets --id X
onecli agents set-secrets --id X --secret-ids a,b
onecli agents set-secret-mode --id X --mode selective
```

--------------------------------

### Manage Secrets via OneCLI

Source: https://www.onecli.sh/docs/cli/onecli-cli

Commands for managing credentials stored in the vault, including listing, creating, updating, and deleting secrets.

```bash
onecli secrets list
onecli secrets create --name X --type anthropic ...
onecli secrets update --id X --value Y
onecli secrets delete --id X
```

--------------------------------

### Test Credential Injection via cURL

Source: https://www.onecli.sh/docs/vaults/bitwarden

Verifies that the OneCLI gateway correctly injects credentials from the Bitwarden vault into an API request.

```bash
curl -x http://x:YOUR_AGENT_TOKEN@localhost:10255 https://api.anthropic.com/v1/messages
```

--------------------------------

### Handle OneCLIRequestError in TypeScript

Source: https://www.onecli.sh/docs/sdks/node

Demonstrates how to catch and handle `OneCLIRequestError` exceptions when making requests using the OneCLI SDK. It shows how to access properties like `url`, `statusCode`, and `message` for detailed error information.

```typescript
import { OneCLIRequestError } from "@onecli-sh/sdk";

try {
  await onecli.getContainerConfig();
} catch (error) {
  if (error instanceof OneCLIRequestError) {
    console.error(error.url);
    console.error(error.statusCode);
    console.error(error.message);
  }
}
```
Tokens:
Raw