OpenCode SDK for Rust

https://github.com/longcipher/opencode-sdk-rs
Admin
A type-safe Rust client library for the OpenCode API with automatic retries, SSE streaming, and...
Tokens:72,744
Snippets:444
Trust Score:5.9
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Quick start: create client and list sessions

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/README.md

Quick start example showing how to create an Opencode client, fetch app information, and list sessions. Uses the default environment configuration and requires the tokio runtime.

```rust
use opencode_sdk_rs::{Opencode, OpencodeError};

#[tokio::main]
async fn main() -> Result<(), OpencodeError> {
    // Create client from environment or defaults
    let client = Opencode::new()?;

    // Get app information
    let app = client.app().get(None).await?;
    println!("Connected to: {}", app.hostname);

    // List sessions
    let sessions = client.session().list(None).await?;
    println!("Found {} sessions", sessions.len());

    Ok(())
}
```

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

### Get app info example

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/app.md

Example usage of AppResource::get. Calls get with no options and prints the hostname, git, and root path from the returned App.

```rust
let app = client.app().get(None).await?;
println!("host={} git={} root={}", app.hostname, app.git, app.path.root);
```

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

### Run basic example with cargo run

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/README.md

Run the basic example from the examples directory using Cargo.

```bash
# Run basic example
cargo run -p opencode-sdk-rs --example basic
```

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

### Install Prism and run contract tests

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/README.md

Install Stoplight Prism and run the OpenAPI contract tests. The test-prism recipe starts a Prism mock server, runs the tests, and shuts down Prism automatically; tests skip when PRISM_URL is not set.

```bash
# Install Prism (one-time)
npm install

# Run Prism contract tests
just test-prism
```

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

### ConfigResource get basic usage

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/config.md

A basic example showing how to retrieve the configuration and access its fields.

```rust
let config = client.config().get(None).await?;
if let Some(theme) = &config.theme {
    println!("theme: {theme}");
}
println!("default model: {:?}", config.model);
```

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

### Initialize app example

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/app.md

Example usage of AppResource::init. Calls init with no options and asserts the returned boolean is true.

```rust
let ok = client.app().init(None).await?;
assert!(ok);
```

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

### Examples

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/client.md

Examples demonstrating basic usage and error handling for the low-level HTTP methods.

```APIDOC
## Example — basic usage

### Description
Demonstrates basic usage of the low-level API: creating a client, making a GET request to an arbitrary path, and using per-request options.

### Code
```rust
use opencode_sdk_rs::{Opencode, OpencodeError};

#[tokio::main]
async fn main() -> Result<(), OpencodeError> {
    let client = Opencode::new()?; // OPENCODE_BASE_URL or http://localhost:54321

    // Low-level request to an arbitrary path:
    let health: serde_json::Value = client.get("/global/health", None).await?;
    println!("health: {health}");

    // Per-request override:
    let mut opts = opencode_sdk_rs::RequestOptions::default();
    opts.timeout = Some(std::time::Duration::from_secs(90));
    let app = client.app().get(Some(&opts)).await?;
    println!("connected to {}", app.hostname);
    Ok(())
}
```
```

```APIDOC
## Example — error handling on the low-level API

### Description
Demonstrates error handling for the low-level API, matching on `OpencodeError::Api` for non-2xx responses and checking retryability.

### Code
```rust
use opencode_sdk_rs::{Opencode, OpencodeError};

#[tokio::main]
async fn main() {
    let client = Opencode::new().expect("client");

    // Any non-2xx response maps to OpencodeError::Api with the status code.
    match client.get::<serde_json::Value>("/session/does-not-exist", None).await {
        Err(OpencodeError::Api { status: 404, body, .. }) => {
            eprintln!("not found, server said: {}", body.unwrap_or_default());
        }
        Err(e) if e.is_retryable() => eprintln!("transient, would retry: {e}"),
        Err(e) => eprintln!("failed: {e}"),
        Ok(_) => unreachable!(),
    }
}
```
```

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

### List files example

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/file.md

Example of listing files in a directory and printing file paths and absolute paths for FileNodeType::File nodes.

```rust
use opencode_sdk_rs::resources::file::FileListParams;

let nodes = client.file().list(Some(&FileListParams { path: "src".into() })).await?;
for node in nodes {
    if node.node_type == FileNodeType::File {
        println!("{} ({})", node.path, node.absolute);
    }
}
```

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

### open_help usage example

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/tui.md

Example of calling `open_help` to open the help panel in the running TUI. Provides a comment noting the effect.

```rust
client.tui().open_help().await?; // opens help in the running TUI
```

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

### Get file status example

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/file.md

Example of iterating over file statuses and printing modified files with added and removed line counts.

```rust
for f in client.file().status().await? {
    if f.status == FileStatus::Modified {
        println!("{}: +{} -{}", f.path, f.added, f.removed);
    }
}
```

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

### symbols example

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/find.md

Searches for symbols matching a query and prints each symbol's name, URI, and start position (line and character).

```rust
use opencode_sdk_rs::resources::FindSymbolsParams;

let symbols = client.find().symbols(FindSymbolsParams { query: "my_function".into() }).await?;
for s in symbols {
    let pos = s.location.range.start;
    println!("{} at {}:{}:{}", s.name, s.location.uri, pos.line, pos.character);
}
```

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

### Read file content example

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/file.md

Basic example of reading a file and handling text vs binary content. Uses FileReadParams with a path and matches on FileContentType.

```rust
use opencode_sdk_rs::resources::file::FileReadParams;

let content = client.file().read(&FileReadParams { path: "src/main.rs".into() }).await?;
match content.content_type {
    FileContentType::Text => println!("{}", content.content),
    FileContentType::Binary => println!("base64: {}", content.content),
}
```

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

### List providers example

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/app.md

Example usage of AppResource::providers. Calls providers with no options and prints each provider's default model from the response.

```rust
let resp = client.app().providers(None).await?;
for (provider_id, model_id) in &resp.default {
    println!("{provider_id} defaults to {model_id}");
}
```

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

### List modes example

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/app.md

Example usage of AppResource::modes. Iterates over the returned modes and prints each mode's name.

```rust
for mode in client.app().modes(None).await? {
    println!("{}", mode.name);
}
```

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

### GET /app

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/app.md

Retrieves application information via GET /app.

```APIDOC
## GET /app

### Description
Retrieves application information.

### Method
GET

### Endpoint
/app

### Parameters
#### Query Parameters
- **options** (Option<&RequestOptions>) - Optional - Per-request overrides

### Request Example
No request body required.

### Response
#### Success Response (200)
- **git** (string) - Git information
- **hostname** (string) - Hostname
- **path** (object) - Path information
- **time** (string) - Time information

#### Response Example
{
  "git": "...",
  "hostname": "...",
  "path": { "root": "..." },
  "time": "..."
}
```

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

### Send log entry example

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/app.md

Example usage of AppResource::log. Constructs AppLogParams with level, message, service, and optional extra metadata, then sends it with no request options.

```rust
use opencode_sdk_rs::resources::app::{AppLogParams, LogLevel};

client
    .app()
    .log(
        &AppLogParams {
            level: LogLevel::Info,
            message: "job finished".into(),
            service: "my-worker".into(),
            extra: Some(HashMap::from([("duration_ms".into(), json!(42))])),
        },
        None,
    )
    .await?;
```

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

### POST /app/init

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/app.md

Initialises the application via POST /app/init.

```APIDOC
## POST /app/init

### Description
Initialises the application. No body required.

### Method
POST

### Endpoint
/app/init

### Parameters
#### Query Parameters
- **options** (Option<&RequestOptions>) - Optional - Per-request overrides

### Request Example
No request body required.

### Response
#### Success Response (200)
- **response** (boolean) - Indicates success

#### Response Example
true
```

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

### Basic low-level HTTP usage example

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/client.md

Basic usage of the low-level HTTP API. Creates a client from OPENCODE_BASE_URL or http://localhost:54321, makes a GET request to /global/health, and shows a per-request timeout override via RequestOptions.

```rust
use opencode_sdk_rs::{Opencode, OpencodeError};

#[tokio::main]
async fn main() -> Result<(), OpencodeError> {
    let client = Opencode::new()?; // OPENCODE_BASE_URL or http://localhost:54321

    // Low-level request to an arbitrary path:
    let health: serde_json::Value = client.get("/global/health", None).await?;
    println!("health: {health}");

    // Per-request override:
    let mut opts = opencode_sdk_rs::RequestOptions::default();
    opts.timeout = Some(std::time::Duration::from_secs(90));
    let app = client.app().get(Some(&opts)).await?;
    println!("connected to {}", app.hostname);
    Ok(())
}
```

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

### Event and File Endpoints

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/endpoints.md

Documentation for the GET /event, GET /file, and GET /file/content endpoints.

```APIDOC
## GET /event

### Description
Opens an SSE event stream that yields a sequence of events. Each event's `data:` field is a JSON object with a `type` discriminator and a `properties` payload.

### Method
GET

### Endpoint
/event

### Parameters
None

### Response
#### Success Response (200)
- **body** (text/event-stream) - Each SSE event's `data:` field is a JSON object with a `type` discriminator (one of 46 kinds) and a `properties` payload.

#### Response Example
```
data: {"type": "session.created", "properties": {}}

```

### Errors
- Non-2xx at connect → `OpencodeError::Api`
- Mid-stream → `Connection` / `Serialization`

## GET /file

### Description
Lists files in a directory. Returns an array of file nodes with metadata.

### Method
GET

### Endpoint
/file

### Parameters
#### Query Parameters
- **path** (string) - Optional - The directory path to list.

### Response
#### Success Response (200)
- **body** (FileNode[]) - Array of file nodes, each with `name`, `path`, `absolute`, `type` ("file" or "directory"), and `ignored`.

#### Response Example
```json
[{"name": "file.txt", "path": "/dir/file.txt", "absolute": "/abs/dir/file.txt", "type": "file", "ignored": false}]
```

### Errors
- Non-2xx → `OpencodeError::Api`

## GET /file/content

### Description
Reads the content of a file. Returns the file content along with optional diff and patch information.

### Method
GET

### Endpoint
/file/content

### Parameters
#### Query Parameters
- **path** (string) - Required - The path of the file to read.

### Response
#### Success Response (200)
- **body** (FileContent) - Object with `type` ("text" or "binary"), `content`, optional `diff`, `patch`, `encoding`, and `mimeType`.

#### Response Example
```json
{"type": "text", "content": "file contents", "encoding": "utf-8", "mimeType": "text/plain"}
```

### Errors
- 404 (file missing) → `OpencodeError::Api` with `status: 404`
```

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

### Opencode::new

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/client.md

Creates a client with default configuration, reading OPENCODE_BASE_URL from the environment (default http://localhost:54321), timeout of 60s, and max_retries=2.

```APIDOC
## Opencode::new

### Description
Creates a client with default configuration: reads `OPENCODE_BASE_URL` from the environment (falls back to `http://localhost:54321`), timeout of 60 s, `max_retries = 2`.

### Method
Constructor

### Signature
```rust
pub fn new() -> Result<Self, OpencodeError>
```

### Parameters
None

### Returns
`Result<Opencode, OpencodeError>` — the client, or `OpencodeError::Http` if the underlying `hpx::Client` cannot be built (e.g. TLS back-end init failure).
```

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

### GET /config/providers

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/app.md

Lists providers and their default models via GET /config/providers.

```APIDOC
## GET /config/providers

### Description
Lists providers and their default models.

### Method
GET

### Endpoint
/config/providers

### Parameters
#### Query Parameters
- **options** (Option<&RequestOptions>) - Optional - Per-request overrides

### Request Example
No request body required.

### Response
#### Success Response (200)
- **default** (object) - Map of provider IDs to default model IDs
- **providers** (array) - List of providers

#### Response Example
{
  "default": { "provider1": "model1" },
  "providers": []
}
```

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

### SessionResource example implementation

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/specs/opencode-sdk-rust/design.md

Shows a resource struct with create and chat methods that POST to the /session endpoint. The chat method formats the session ID into the URL path.

```rust
pub struct SessionResource<'a> {
    client: &'a Opencode,
}

impl<'a> SessionResource<'a> {
    pub async fn create(&self) -> Result<Session, OpencodeError> {
        self.client.post("/session", None::<()>).await
    }

    pub async fn chat(&self, id: &str, params: SessionChatParams) -> Result<AssistantMessage, OpencodeError> {
        self.client.post(&format!("/session/{id}/message"), Some(params)).await
    }
    // ... etc
}
```

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

### GET /mode

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/app.md

Lists available operational modes via GET /mode.

```APIDOC
## GET /mode

### Description
Lists available operational modes.

### Method
GET

### Endpoint
/mode

### Parameters
#### Query Parameters
- **options** (Option<&RequestOptions>) - Optional - Per-request overrides

### Request Example
No request body required.

### Response
#### Success Response (200)
- **name** (string) - Mode name
- **tools** (object) - Map of tool names to booleans
- **model** (object) - Optional model configuration
- **prompt** (string) - Optional prompt
- **temperature** (number) - Optional temperature

#### Response Example
[
  {
    "name": "...",
    "tools": { "tool1": true },
    "model": {},
    "prompt": "...",
    "temperature": 0.7
  }
]
```

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

### Build, Lint, and Test Commands (just)

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/AGENTS.md

Common commands for formatting, linting, testing, and building the project using the 'just' command runner. Use 'just format' for formatting, 'just lint' for all lints, 'just test' to run all tests, and 'just ci' for a full CI check.

```bash
# Format all code (Rust, TOML, Markdown)
just format

# Run all lints (typos, markdown, clippy, unused deps check)
just lint

# Run all tests
just test

# Run a single test by name
just test -- <test_name>

# Run tests with coverage
just test-coverage

# Check compilation without building
just check

# Full CI check (lint + test + build)
just ci

# Clean build artifacts
just clean
```

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

### FileResource::status method signature

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/file.md

Signature for the status method that performs GET /file/status to get the status of all files in the project.

```rust
pub async fn status(&self) -> Result<FileStatusResponse, OpencodeError>
```

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

### Build with cargo build

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/README.md

Build the project with Cargo.

```bash
cargo build
```

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

### files basic example

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/find.md

Searches for files matching a glob pattern and prints each matching path. Uses `FindFilesParams` with `query` set to `"*.rs"`.

```rust
use opencode_sdk_rs::resources::FindFilesParams;

let files = client.find().files(FindFilesParams { query: "*.rs".into() }).await?;
for path in files {
    println!("{path}");
}
```

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

### Get config and print theme

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/README.md

Retrieve the current configuration and print the theme if it is set. The theme field is optional, so use if let to handle the Option.

```rust
let config = client.config().get(None).await?;
if let Some(theme) = &config.theme {
    println!("Current theme: {}", theme);
}
```

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

### Opencode::new constructor

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/client.md

Creates a client with default configuration: reads OPENCODE_BASE_URL from the environment (falls back to http://localhost:54321), timeout of 60 s, max_retries = 2. Returns Result<Opencode, OpencodeError>; OpencodeError::Http if the underlying hpx::Client cannot be built.

```rust
pub fn new() -> Result<Self, OpencodeError>
```

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

### Opencode::with_options

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/client.md

Creates a client from explicit ClientOptions. Unset option fields fall back to the same defaults as new().

```APIDOC
## Opencode::with_options

### Description
Creates a client from explicit `ClientOptions`. Unset option fields fall back to the same defaults as `new()`.

### Method
Constructor

### Signature
```rust
pub fn with_options(opts: &ClientOptions) -> Result<Self, OpencodeError>
```

### Parameters
- **opts** (`&ClientOptions`) - Required - Full option set; `None` fields resolve to defaults

### Returns
Same as `new()`.
```

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

### append_prompt basic usage example

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/tui.md

Example of calling `append_prompt` with a `TuiAppendPromptParams` struct containing the text to append. Uses the `?` operator to propagate errors.

```rust
use opencode_sdk_rs::resources::tui::TuiAppendPromptParams;

client
    .tui()
    .append_prompt(&TuiAppendPromptParams { text: "cargo build".into() })
    .await?;
```

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

### status

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/file.md

Gets the status of all files in the project via GET /file/status. Returns a vector of file status entries with added, removed, and status fields.

```APIDOC
## GET /file/status

### Description
Gets the status of all files in the project.

### Method
GET

### Endpoint
/file/status

### Parameters
None

### Request Example
GET /file/status

### Response
#### Success Response (200)
- **added** (integer) - Number of added lines.
- **path** (string) - The file path.
- **removed** (integer) - Number of removed lines.
- **status** (string) - The file status: `added`, `deleted`, or `modified`.

#### Response Example
[
  {
    "added": 10,
    "path": "src/main.rs",
    "removed": 5,
    "status": "modified"
  }
]
```

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

### POST /session/{id}/init

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/endpoints.md

Initialises a session with the given parameters.

```APIDOC
## POST /session/{id}/init

### Description
Initialises a session with the given parameters.

### Method
POST

### Endpoint
/session/{id}/init

### Parameters
#### Path Parameters
- **id** (string) - Required - Session identifier.

#### Request Body
- **messageID** (string) - Required - Message identifier.
- **modelID** (string) - Required - Model identifier.
- **providerID** (string) - Required - Provider identifier.

### Response
#### Success Response (200)
- **boolean** - Success indicator.

#### Response Example
```json
true
```

### Errors
- non-2xx → `OpencodeError::Api`
```

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

### Run CI checks with just

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/AGENTS.md

Run all required checks before submitting: format, lint, test, and build.

```bash
just format
just lint
just test
just build
```

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

### GET /find

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/endpoints.md

Searches for text in the project.

```APIDOC
## GET /find

### Description
Searches for text in the project.

### Method
GET

### Endpoint
/find

### Parameters
#### Query Parameters
- **pattern** (string) - Required - The text pattern to search for.

### Response
#### Success Response (200)
- **FindTextResponseItem[]** (array) - Array of search result items.
  - **absolute_offset** (number) - Absolute offset of the match.
  - **line_number** (number) - Line number of the match.
  - **lines** (object) - Lines containing the match.
    - **text** (string) - The line text.
  - **path** (object) - Path of the file.
    - **text** (string) - The file path.
  - **submatches** (array) - Array of submatches.
    - **end** (number) - End position.
    - **match** (object) - The matched text.
      - **text** (string) - The matched text.
    - **start** (number) - Start position.

#### Response Example
```json
[
  {
    "absolute_offset": 0,
    "line_number": 1,
    "lines": { "text": "fn main() {}" },
    "path": { "text": "src/main.rs" },
    "submatches": [
      { "end": 2, "match": { "text": "fn" }, "start": 0 }
    ]
  }
]
```

### Errors
- Non-2xx status code → `OpencodeError::Api`
```

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

### init

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/api-reference/session.md

Initialises a session with the given message, model, and provider.

```APIDOC
## POST /session/{id}/init

### Description
Initialises a session.

### Method
POST

### Endpoint
/session/{id}/init

### Parameters
#### Path Parameters
- **id** (string) - Required - Session ID

#### Request Body
- **messageID** (string) - Required - Message ID
- **modelID** (string) - Required - Model ID
- **providerID** (string) - Required - Provider ID

### Request Example
```json
{
  "messageID": "msg_123",
  "modelID": "claude-sonnet",
  "providerID": "anthropic"
}
```

### Response
#### Success Response (200)
- **body** (boolean) - True if initialisation succeeded

#### Response Example
```json
true
```
```

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

### GET /find/symbol

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/endpoints.md

Searches for symbols in the codebase.

```APIDOC
## GET /find/symbol

### Description
Searches for symbols in the codebase.

### Method
GET

### Endpoint
/find/symbol

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query.

### Response
#### Success Response (200)
- **SymbolInfo[]** (array) - Array of symbol information objects.
  - **kind** (number) - The kind of symbol.
  - **location** (object) - Location of the symbol.
    - **range** (object) - Range of the symbol.
      - **start** (object) - Start position.
        - **line** (number) - Line number.
        - **character** (number) - Character number.
      - **end** (object) - End position.
        - **line** (number) - Line number.
        - **character** (number) - Character number.
    - **uri** (string) - URI of the file.
  - **name** (string) - Symbol name.

#### Response Example
```json
[
  {
    "kind": 12,
    "location": {
      "range": {
        "start": { "line": 0, "character": 0 },
        "end": { "line": 0, "character": 10 }
      },
      "uri": "file:///path/to/file.rs"
    },
    "name": "my_function"
  }
]
```

### Errors
- Non-2xx status code → `OpencodeError::Api`
```

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

### GET /session/{id}/message

Source: https://github.com/longcipher/opencode-sdk-rs/blob/master/_autodocs/endpoints.md

Lists messages in a session.

```APIDOC
## GET /session/{id}/message

### Description
Lists messages in a session.

### Method
GET

### Endpoint
/session/{id}/message

### Parameters
#### Path Parameters
- **id** (string) - Required - Session identifier.

### Response
#### Success Response (200)
- **SessionMessagesResponseItem[]** - Array of session message items.

#### Response Example
```json
[]
```

### Errors
- 404 → `OpencodeError::Api`
```
Tokens:
Raw