# Reference
<details><summary><code>client.<a href="src/terminaluse/client.py">search</a>(...) -> SearchResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Unified search endpoint for agents, tasks, and workspaces.

    Searches by name using case-insensitive matching.
    Results are sorted by relevance (exact matches first, then prefix matches, then contains).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.search(
    q="q",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**q:** `str` — Search query (minimum 2 characters)
    
</dd>
</dl>

<dl>
<dd>

**types:** `typing.Optional[str]` — Comma-separated list of types to search (agents,tasks,workspaces). If not provided, searches all types.
    
</dd>
</dl>

<dl>
<dd>

**namespace_id:** `typing.Optional[str]` — Optional namespace ID to filter results
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Maximum number of results per type (max 50)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Telemetry
<details><summary><code>client.telemetry.<a href="src/terminaluse/telemetry/client.py">agent_metrics_ingest</a>(...) -> MetricsIngestionResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Ingest OpenTelemetry metrics from an agent. Requires agent API key authentication.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.telemetry.agent_metrics_ingest(
    resource_metrics=[
        {
            "key": "value"
        }
    ],
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**resource_metrics:** `typing.List[typing.Dict[str, typing.Any]]` — Array of ResourceMetrics as per OTLP JSON format
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.telemetry.<a href="src/terminaluse/telemetry/client.py">traces_ingest</a>(...) -> TraceIngestionResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Ingest OpenTelemetry traces from an agent. Requires agent API key authentication.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.telemetry.traces_ingest(
    resource_spans=[
        {
            "key": "value"
        }
    ],
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**resource_spans:** `typing.List[typing.Dict[str, typing.Any]]` — Array of ResourceSpans as per OTLP JSON format
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## AgentApiKeys
<details><summary><code>client.agent_api_keys.<a href="src/terminaluse/agent_api_keys/client.py">agent_api_keys_list</a>(...) -> typing.List[AgentApiKey]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List API keys for an agent ID.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agent_api_keys.agent_api_keys_list()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_id:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` 
    
</dd>
</dl>

<dl>
<dd>

**page_number:** `typing.Optional[int]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agent_api_keys.<a href="src/terminaluse/agent_api_keys/client.py">agent_api_keys_create</a>(...) -> CreateApiKeyResponse</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agent_api_keys.agent_api_keys_create(
    name="name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` — The name of the agent's API key.
    
</dd>
</dl>

<dl>
<dd>

**agent_id:** `typing.Optional[str]` — The UUID of the agent
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `typing.Optional[str]` — The name of the agent - if not provided, the agent_id must be set.
    
</dd>
</dl>

<dl>
<dd>

**api_key:** `typing.Optional[str]` — Optionally provide the API key value - if not set, one will be generated.
    
</dd>
</dl>

<dl>
<dd>

**api_key_type:** `typing.Optional[AgentApiKeyType]` — The type of the agent API key (external by default).
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agent_api_keys.<a href="src/terminaluse/agent_api_keys/client.py">agent_api_keys_name_delete</a>(...) -> str</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Delete API key by name.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agent_api_keys.agent_api_keys_name_delete(
    api_key_name="api_key_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**api_key_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_id:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**api_key_type:** `typing.Optional[AgentApiKeyType]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agent_api_keys.<a href="src/terminaluse/agent_api_keys/client.py">agent_api_keys_name_retrieve</a>(...) -> AgentApiKey</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Return named API key for the agent ID.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agent_api_keys.agent_api_keys_name_retrieve(
    name="name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_id:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**api_key_type:** `typing.Optional[AgentApiKeyType]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agent_api_keys.<a href="src/terminaluse/agent_api_keys/client.py">agent_api_keys_retrieve</a>(...) -> AgentApiKey</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Return API key by ID.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agent_api_keys.agent_api_keys_retrieve(
    id="id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agent_api_keys.<a href="src/terminaluse/agent_api_keys/client.py">agent_api_keys_delete</a>(...) -> str</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Delete API key by ID.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agent_api_keys.agent_api_keys_delete(
    id="id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Agents
<details><summary><code>client.agents.<a href="src/terminaluse/agents/client.py">list</a>(...) -> typing.List[AgentListItem]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List all registered agents, optionally filtered by query parameters.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.list()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `typing.Optional[str]` — Task ID
    
</dd>
</dl>

<dl>
<dd>

**namespace_id:** `typing.Optional[str]` — Filter by namespace ID
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Limit
    
</dd>
</dl>

<dl>
<dd>

**page_number:** `typing.Optional[int]` — Page number
    
</dd>
</dl>

<dl>
<dd>

**order_by:** `typing.Optional[str]` — Field to order by
    
</dd>
</dl>

<dl>
<dd>

**order_direction:** `typing.Optional[str]` — Order direction (asc or desc)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.<a href="src/terminaluse/agents/client.py">deploy</a>(...) -> DeployResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deploy an agent to the platform.

    Called by CLI after pushing the container image to the registry.
    Creates or updates agent, branch, and version records.

    The deployment is asynchronous - poll GET /branches/{branch_id}
    for status updates until status is READY or FAILED.

    **Flow:**
    1. CLI builds and pushes image to registry (using /registry/auth)
    2. CLI calls POST /agents/deploy with image details
    3. Platform creates records and triggers K8s deployment
    4. Container starts and calls POST /versions/register
    5. CLI polls GET /branches/{id} for status
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.deploy(
    agent_name="agent_name",
    author_email="author_email",
    author_name="author_name",
    branch="branch",
    git_hash="git_hash",
    image_url="image_url",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_name:** `str` — Agent name in 'namespace_slug/agent_name' format (lowercase alphanumeric, hyphens, underscores)
    
</dd>
</dl>

<dl>
<dd>

**author_email:** `str` — Git commit author email
    
</dd>
</dl>

<dl>
<dd>

**author_name:** `str` — Git commit author name
    
</dd>
</dl>

<dl>
<dd>

**branch:** `str` — Git branch name (e.g., 'main', 'feature/new-tool')
    
</dd>
</dl>

<dl>
<dd>

**git_hash:** `str` — Git commit hash (short or full)
    
</dd>
</dl>

<dl>
<dd>

**image_url:** `str` — Full container image URL (e.g., 'us-east4-docker.pkg.dev/proj/repo/agent:hash')
    
</dd>
</dl>

<dl>
<dd>

**acp_type:** `typing.Optional[AcpType]` — ACP server type (sync or async)
    
</dd>
</dl>

<dl>
<dd>

**are_tasks_sticky:** `typing.Optional[bool]` — If true, running tasks stay on their original version until completion during this deploy. If false or None, tasks are migrated to the new version immediately.
    
</dd>
</dl>

<dl>
<dd>

**description:** `typing.Optional[str]` — Agent description (used when creating new agent)
    
</dd>
</dl>

<dl>
<dd>

**git_message:** `typing.Optional[str]` — Git commit message (truncated if too long)
    
</dd>
</dl>

<dl>
<dd>

**is_dirty:** `typing.Optional[bool]` — Whether the working directory had uncommitted changes at deploy time
    
</dd>
</dl>

<dl>
<dd>

**replicas:** `typing.Optional[int]` — Desired replica count (1-10)
    
</dd>
</dl>

<dl>
<dd>

**resources:** `typing.Optional[typing.Dict[str, typing.Any]]` — Resource requests and limits (e.g., {'requests': {'cpu': '100m', 'memory': '256Mi'}, 'limits': {'cpu': '1000m', 'memory': '1Gi'}})
    
</dd>
</dl>

<dl>
<dd>

**sdk_type:** `typing.Optional[SdkType]` — SDK type for agent runtime
    
</dd>
</dl>

<dl>
<dd>

**source_filesystem_id:** `typing.Optional[str]` — Filesystem snapshot containing the deploy source for Builder reopenability
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.<a href="src/terminaluse/agents/client.py">forward_get_by_name</a>(...) -> typing.Any</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Forward a GET request to an agent by namespace and name.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.forward_get_by_name(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
    path="path",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**path:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.<a href="src/terminaluse/agents/client.py">rpc_by_name</a>(...) -> typing.Any</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Forward a POST request to an agent by namespace and name.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.rpc_by_name(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
    path="path",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**path:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.<a href="src/terminaluse/agents/client.py">retrieve_by_name</a>(...) -> Agent</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get an agent by namespace slug and agent name.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.retrieve_by_name(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.<a href="src/terminaluse/agents/client.py">delete_by_name</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Delete an agent by namespace slug and agent name.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.delete_by_name(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.<a href="src/terminaluse/agents/client.py">retrieve</a>(...) -> Agent</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get an agent by its unique ID.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.retrieve(
    agent_id="agent_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.<a href="src/terminaluse/agents/client.py">delete</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Delete an agent by its unique ID.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.delete(
    agent_id="agent_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.<a href="src/terminaluse/agents/client.py">retrieve_metrics</a>(...) -> AgentMetricsResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get aggregated metrics for an agent over the last 24 hours. Includes task success rate, task count, error log count, and average task duration.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.retrieve_metrics(
    agent_id="agent_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**branch_id:** `typing.Optional[str]` — Optional branch ID filter
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Schedules
<details><summary><code>client.schedules.<a href="src/terminaluse/schedules/client.py">agents_schedules_list</a>(...) -> ScheduleListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List all schedules for an agent.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.schedules.agents_schedules_list(
    agent_id="agent_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**page_size:** `typing.Optional[int]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.schedules.<a href="src/terminaluse/schedules/client.py">agents_schedules_create</a>(...) -> ScheduleResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Create a new schedule for recurring workflow execution for an agent.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.schedules.agents_schedules_create(
    agent_id="agent_id",
    name="name",
    task_queue="task_queue",
    workflow_name="workflow_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**name:** `str` — Human-readable name for the schedule (e.g., 'weekly-profiling'). Will be combined with agent_id to form the full schedule_id.
    
</dd>
</dl>

<dl>
<dd>

**task_queue:** `str` — Temporal task queue where the agent's worker is listening
    
</dd>
</dl>

<dl>
<dd>

**workflow_name:** `str` — Name of the Temporal workflow to execute (e.g., 'sae-orchestrator')
    
</dd>
</dl>

<dl>
<dd>

**cron_expression:** `typing.Optional[str]` — Cron expression for scheduling (e.g., '0 0 * * 0' for weekly on Sunday)
    
</dd>
</dl>

<dl>
<dd>

**end_at:** `typing.Optional[datetime.datetime]` — When the schedule should stop being active
    
</dd>
</dl>

<dl>
<dd>

**execution_timeout_seconds:** `typing.Optional[int]` — Maximum time in seconds for each workflow execution
    
</dd>
</dl>

<dl>
<dd>

**interval_seconds:** `typing.Optional[int]` — Alternative to cron - run every N seconds
    
</dd>
</dl>

<dl>
<dd>

**paused:** `typing.Optional[bool]` — Whether to create the schedule in a paused state
    
</dd>
</dl>

<dl>
<dd>

**start_at:** `typing.Optional[datetime.datetime]` — When the schedule should start being active
    
</dd>
</dl>

<dl>
<dd>

**workflow_params:** `typing.Optional[typing.Dict[str, typing.Any]]` — Parameters to pass to the workflow
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.schedules.<a href="src/terminaluse/schedules/client.py">agents_schedules_retrieve</a>(...) -> ScheduleResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get details of a schedule by its name.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.schedules.agents_schedules_retrieve(
    agent_id="agent_id",
    schedule_name="schedule_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**schedule_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.schedules.<a href="src/terminaluse/schedules/client.py">agents_schedules_delete</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Delete a schedule permanently.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.schedules.agents_schedules_delete(
    agent_id="agent_id",
    schedule_name="schedule_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**schedule_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.schedules.<a href="src/terminaluse/schedules/client.py">agents_schedules_pause</a>(...) -> ScheduleResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Pause a schedule to stop it from executing.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase, PauseScheduleRequest

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.schedules.agents_schedules_pause(
    agent_id="agent_id",
    schedule_name="schedule_name",
    request=PauseScheduleRequest(),
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**schedule_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request:** `typing.Optional[PauseScheduleRequest]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.schedules.<a href="src/terminaluse/schedules/client.py">agents_schedules_trigger</a>(...) -> ScheduleResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Trigger a schedule to run immediately, regardless of its regular schedule.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.schedules.agents_schedules_trigger(
    agent_id="agent_id",
    schedule_name="schedule_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**schedule_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.schedules.<a href="src/terminaluse/schedules/client.py">agents_schedules_unpause</a>(...) -> ScheduleResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Unpause/resume a schedule to allow it to execute again.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase, UnpauseScheduleRequest

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.schedules.agents_schedules_unpause(
    agent_id="agent_id",
    schedule_name="schedule_name",
    request=UnpauseScheduleRequest(),
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**schedule_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request:** `typing.Optional[UnpauseScheduleRequest]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Branches
<details><summary><code>client.branches.<a href="src/terminaluse/branches/client.py">agents_environments_rollback_create</a>(...) -> RollbackResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Roll back an environment to a previous version.

    Resolves environment to branch via branch rules.
    Only works for environments with a single, literal branch rule (no wildcards).

    Key behavior:
    - EnvVar table is NOT modified (remains pending state for next deploy)
    - Uses Version.secrets_snapshot as deployed state
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.branches.agents_environments_rollback_create(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
    env_name="env_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**env_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request:** `RollbackRequest` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.branches.<a href="src/terminaluse/branches/client.py">retrieve</a>(...) -> BranchResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get branch details by ID.

    Used by CLI to poll for branch status after calling POST /agents/deploy.
    Poll until status is READY (success) or FAILED/TIMEOUT (failure).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.branches.retrieve(
    branch_id="branch_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**branch_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.branches.<a href="src/terminaluse/branches/client.py">redeploy</a>(...) -> RedeployResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Redeploy a branch with the current secrets from the EnvVar table.

    Creates a new Version with:
    - Same image as current version
    - Fresh secrets_snapshot from current EnvVars

    Use this after updating secrets to apply them to a running branch.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.branches.redeploy(
    branch_id="branch_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**branch_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.branches.<a href="src/terminaluse/branches/client.py">rollback</a>(...) -> RollbackResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Roll back a branch to a previous version by branch ID.

    Key behavior:
    - EnvVar table is NOT modified (remains pending state)
    - Uses Version.secrets_snapshot as deployed state
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.branches.rollback(
    branch_id="branch_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**branch_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request:** `RollbackRequest` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## ApiKeys
<details><summary><code>client.api_keys.<a href="src/terminaluse/api_keys/client.py">list</a>(...) -> ApiKeyListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List all API keys for the organization. Only org admins can list keys.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.api_keys.list()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**include_revoked:** `typing.Optional[bool]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.api_keys.<a href="src/terminaluse/api_keys/client.py">create</a>(...) -> ApiKeyCreateResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Create a new org-level API key. Only org admins can create API keys.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase, ApiKeyScope

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.api_keys.create(
    name="name",
    scopes=[
        ApiKeyScope(
            resource_id="resource_id",
            resource_type="resource_type",
            role="discoverer",
        )
    ],
    sharing_group_ids=[
        "sharing_group_ids"
    ],
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` — Human-readable name for the API key.
    
</dd>
</dl>

<dl>
<dd>

**scopes:** `typing.List[ApiKeyScope]` — List of resource scopes. At least one scope is required.
    
</dd>
</dl>

<dl>
<dd>

**sharing_group_ids:** `typing.List[str]` — IDs of groups that receive default admin grants on key-created resources.
    
</dd>
</dl>

<dl>
<dd>

**description:** `typing.Optional[str]` — Optional description.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.api_keys.<a href="src/terminaluse/api_keys/client.py">retrieve</a>(...) -> ApiKeyResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get details of a specific API key. Only org admins can view keys.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.api_keys.retrieve(
    api_key_id="api_key_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**api_key_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.api_keys.<a href="src/terminaluse/api_keys/client.py">delete</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Revoke an API key. Only org admins can revoke keys.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.api_keys.delete(
    api_key_id="api_key_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**api_key_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.api_keys.<a href="src/terminaluse/api_keys/client.py">update_scopes</a>(...) -> ApiKeyResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Update scopes for an API key. Only org admins can update key scopes.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase, ApiKeyScope

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.api_keys.update_scopes(
    api_key_id="api_key_id",
    scopes=[
        ApiKeyScope(
            resource_id="resource_id",
            resource_type="resource_type",
            role="discoverer",
        )
    ],
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**api_key_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**scopes:** `typing.List[ApiKeyScope]` — Updated list of resource scopes.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.api_keys.<a href="src/terminaluse/api_keys/client.py">update_sharing_groups</a>(...) -> ApiKeyResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Update default sharing groups for resources created by an API key.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.api_keys.update_sharing_groups(
    api_key_id="api_key_id",
    sharing_group_ids=[
        "sharing_group_ids"
    ],
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**api_key_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**sharing_group_ids:** `typing.List[str]` — Replacement sharing groups (future creations only).
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Builds
<details><summary><code>client.builds.<a href="src/terminaluse/builds/client.py">prepare</a>(...) -> BuildPrepareResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Return a presigned URL for uploading a build context archive to GCS.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.builds.prepare(
    agent_name="my-agent",
    namespace="acme",
    tag="abc123def456",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_name:** `str` — Agent short name (without namespace prefix)
    
</dd>
</dl>

<dl>
<dd>

**namespace:** `str` — Target namespace slug for the build
    
</dd>
</dl>

<dl>
<dd>

**tag:** `str` — Image tag to build/push (typically git hash)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.builds.<a href="src/terminaluse/builds/client.py">submit</a>(...) -> BuildSubmitResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Submit a Cloud Build build for an uploaded build context archive.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.builds.submit(
    agent_name="agent_name",
    bucket="bucket",
    namespace="namespace",
    object_key="object_key",
    tag="tag",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_name:** `str` — Agent short name
    
</dd>
</dl>

<dl>
<dd>

**bucket:** `str` — GCS bucket containing uploaded build context archive.
    
</dd>
</dl>

<dl>
<dd>

**namespace:** `str` — Target namespace slug
    
</dd>
</dl>

<dl>
<dd>

**object_key:** `str` — GCS object key for the uploaded build context archive.
    
</dd>
</dl>

<dl>
<dd>

**tag:** `str` — Image tag to build/push
    
</dd>
</dl>

<dl>
<dd>

**git_branch:** `typing.Optional[str]` — Optional git branch name for metadata.
    
</dd>
</dl>

<dl>
<dd>

**git_hash:** `typing.Optional[str]` — Optional git hash for metadata.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.builds.<a href="src/terminaluse/builds/client.py">retrieve</a>(...) -> BuildStatusResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get build status for a Cloud Build build ID (proxied).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.builds.retrieve(
    build_id="build_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**build_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Events
<details><summary><code>client.events.<a href="src/terminaluse/events/client.py">list</a>(...) -> typing.List[Event]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List events for a specific task and agent.

Optionally filter for events after a specific sequence ID.
Results are ordered by sequence_id.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.events.list(
    task_id="task_id",
    agent_id="agent_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `str` — The task ID
    
</dd>
</dl>

<dl>
<dd>

**agent_id:** `str` — The agent ID
    
</dd>
</dl>

<dl>
<dd>

**last_processed_event_id:** `typing.Optional[str]` — Optional event ID to get events after this ID
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Optional limit on number of results
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.events.<a href="src/terminaluse/events/client.py">retrieve</a>(...) -> Event</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.events.retrieve(
    event_id="event_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**event_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Filesystems
<details><summary><code>client.filesystems.<a href="src/terminaluse/filesystems/client.py">list</a>(...) -> typing.List[FilesystemResponse]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List all filesystems accessible to the current user.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.filesystems.list()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**project_id:** `typing.Optional[str]` — Optional project filter. When provided, requires read access to the project and returns only filesystems in that project.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.filesystems.<a href="src/terminaluse/filesystems/client.py">create</a>(...) -> FilesystemResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Create a new filesystem linked to a project.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.filesystems.create(
    project_id="project_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**project_id:** `str` — Project ID. Filesystem inherits permissions from the project.
    
</dd>
</dl>

<dl>
<dd>

**name:** `typing.Optional[str]` — Optional human-readable name for the filesystem (unique per namespace).
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.filesystems.<a href="src/terminaluse/filesystems/client.py">retrieve</a>(...) -> FilesystemResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get filesystem details by ID.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.filesystems.retrieve(
    filesystem_id="filesystem_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**filesystem_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.filesystems.<a href="src/terminaluse/filesystems/client.py">get_download_url</a>(...) -> PresignedUrlResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get a presigned URL for direct download from GCS.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase, PresignedUrlRequest

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.filesystems.get_download_url(
    filesystem_id="filesystem_id",
    request=PresignedUrlRequest(),
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**filesystem_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request:** `typing.Optional[PresignedUrlRequest]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.filesystems.<a href="src/terminaluse/filesystems/client.py">download_file</a>(...) -> typing.Iterator[bytes]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Download a single file from the filesystem.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.filesystems.download_file(
    filesystem_id="filesystem_id",
    path="path",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**filesystem_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**path:** `str` — Relative file path to download.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.filesystems.<a href="src/terminaluse/filesystems/client.py">upload_file</a>(...) -> SingleFileUploadResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Upload a single file into a filesystem by relative path. Defaults to overwrite mode; conditional mode can be used for strict concurrency control.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
client.filesystems.upload_file(...)
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**filesystem_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**path:** `str` — Relative path to write.
    
</dd>
</dl>

<dl>
<dd>

**request:** `typing.Union[bytes, typing.Iterator[bytes], typing.AsyncIterator[bytes]]` 
    
</dd>
</dl>

<dl>
<dd>

**write_mode:** `typing.Optional[FileUploadWriteMode]` — Upload semantics: overwrite (default) or conditional.
    
</dd>
</dl>

<dl>
<dd>

**base_version:** `typing.Optional[str]` — Required in conditional mode: expected current archive version.
    
</dd>
</dl>

<dl>
<dd>

**expected_version:** `typing.Optional[str]` — Conditional replace precondition on current file version.
    
</dd>
</dl>

<dl>
<dd>

**create_only:** `typing.Optional[str]` — Conditional create precondition; must be '*'.
    
</dd>
</dl>

<dl>
<dd>

**digest:** `typing.Optional[str]` — Optional digest in format sha-256=<base64>.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.filesystems.<a href="src/terminaluse/filesystems/client.py">list_files</a>(...) -> ListFilesResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List files in the filesystem manifest with optional filtering.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.filesystems.list_files(
    filesystem_id="filesystem_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**filesystem_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**directory:** `typing.Optional[str]` — Directory prefix to filter results
    
</dd>
</dl>

<dl>
<dd>

**recursive:** `typing.Optional[bool]` — Include subdirectories
    
</dd>
</dl>

<dl>
<dd>

**mime_type:** `typing.Optional[str]` — Filter by MIME type
    
</dd>
</dl>

<dl>
<dd>

**include_content:** `typing.Optional[bool]` — Include file content in response
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Maximum number of results
    
</dd>
</dl>

<dl>
<dd>

**offset:** `typing.Optional[int]` — Pagination offset
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.filesystems.<a href="src/terminaluse/filesystems/client.py">get_file</a>(...) -> FilesystemFileResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Retrieve a specific file (or directory) from the filesystem manifest.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.filesystems.get_file(
    filesystem_id="filesystem_id",
    file_path="file_path",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**filesystem_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**file_path:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**include_content:** `typing.Optional[bool]` — Include file content in response
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.filesystems.<a href="src/terminaluse/filesystems/client.py">sync_complete</a>(...) -> SyncCompleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Notify that a sync operation completed and provide the file manifest.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.filesystems.sync_complete(
    filesystem_id="filesystem_id",
    direction="direction",
    status="status",
    sync_id="sync_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**filesystem_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**direction:** `str` — Sync direction: 'UP' or 'DOWN'.
    
</dd>
</dl>

<dl>
<dd>

**status:** `str` — Sync status: 'SUCCESS' or 'FAILED'.
    
</dd>
</dl>

<dl>
<dd>

**sync_id:** `str` — Unique ID for this sync operation (idempotency key).
    
</dd>
</dl>

<dl>
<dd>

**archive_checksum:** `typing.Optional[str]` — SHA256 checksum of the archive.
    
</dd>
</dl>

<dl>
<dd>

**archive_size_bytes:** `typing.Optional[int]` — Size of the archive in bytes.
    
</dd>
</dl>

<dl>
<dd>

**files:** `typing.Optional[typing.List[FilesystemFile]]` — List of files in the filesystem (empty if status is FAILED).
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.filesystems.<a href="src/terminaluse/filesystems/client.py">get_upload_url</a>(...) -> PresignedUrlResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get a presigned URL for direct upload to GCS.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase, PresignedUrlRequest

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.filesystems.get_upload_url(
    filesystem_id="filesystem_id",
    request=PresignedUrlRequest(),
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**filesystem_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request:** `typing.Optional[PresignedUrlRequest]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Groups
<details><summary><code>client.groups.<a href="src/terminaluse/groups/client.py">list</a>(...) -> AccessGroupListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List groups visible to the current principal.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.groups.list()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**owner_org_id:** `typing.Optional[str]` — Optional owner org filter.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` 
    
</dd>
</dl>

<dl>
<dd>

**page_number:** `typing.Optional[int]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.groups.<a href="src/terminaluse/groups/client.py">create</a>(...) -> AccessGroup</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Create an org-owned access group.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.groups.create(
    name="name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` — Group name (unique within owner org).
    
</dd>
</dl>

<dl>
<dd>

**description:** `typing.Optional[str]` — Optional group description.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.groups.<a href="src/terminaluse/groups/client.py">retrieve</a>(...) -> AccessGroup</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get group details.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.groups.retrieve(
    group_id="group_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**group_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.groups.<a href="src/terminaluse/groups/client.py">delete</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Delete an access group.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.groups.delete(
    group_id="group_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**group_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.groups.<a href="src/terminaluse/groups/client.py">update</a>(...) -> AccessGroup</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Update group metadata.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.groups.update(
    group_id="group_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**group_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**description:** `typing.Optional[str]` — Optional group description.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.groups.<a href="src/terminaluse/groups/client.py">managers_list</a>(...) -> AccessGroupManagersResponse</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.groups.managers_list(
    group_id="group_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**group_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.groups.<a href="src/terminaluse/groups/client.py">managers_upsert</a>(...) -> AccessGroupManager</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.groups.managers_upsert(
    group_id="group_id",
    member_id="member_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**group_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**member_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.groups.<a href="src/terminaluse/groups/client.py">managers_delete</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.groups.managers_delete(
    group_id="group_id",
    member_id="member_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**group_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**member_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.groups.<a href="src/terminaluse/groups/client.py">members_list</a>(...) -> AccessGroupMembersResponse</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.groups.members_list(
    group_id="group_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**group_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.groups.<a href="src/terminaluse/groups/client.py">members_upsert</a>(...) -> AccessGroupMember</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.groups.members_upsert(
    group_id="group_id",
    member_id="member_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**group_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**member_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.groups.<a href="src/terminaluse/groups/client.py">members_delete</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.groups.members_delete(
    group_id="group_id",
    member_id="member_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**group_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**member_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.groups.<a href="src/terminaluse/groups/client.py">visible_orgs_list</a>(...) -> AccessGroupVisibleOrgsResponse</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.groups.visible_orgs_list(
    group_id="group_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**group_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.groups.<a href="src/terminaluse/groups/client.py">visible_orgs_upsert</a>(...) -> AccessGroupVisibleOrg</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.groups.visible_orgs_upsert(
    group_id="group_id",
    org_id="org_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**group_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**org_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.groups.<a href="src/terminaluse/groups/client.py">visible_orgs_delete</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.groups.visible_orgs_delete(
    group_id="group_id",
    org_id="org_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**group_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**org_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Logs
<details><summary><code>client.logs.<a href="src/terminaluse/logs/client.py">list</a>(...) -> LogListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Query logs for an agent. Requires user authentication.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.logs.list(
    agent_name="agent_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_name:** `str` — Name of the agent (format: namespace/name or agent ID)
    
</dd>
</dl>

<dl>
<dd>

**branch_id:** `typing.Optional[str]` — Filter by branch/deployment ID
    
</dd>
</dl>

<dl>
<dd>

**task_id:** `typing.Optional[str]` — Filter by task ID
    
</dd>
</dl>

<dl>
<dd>

**trace_id:** `typing.Optional[str]` — Filter by OTEL trace ID (32 lowercase hex chars)
    
</dd>
</dl>

<dl>
<dd>

**level:** `typing.Optional[LogLevel]` — Filter by log level
    
</dd>
</dl>

<dl>
<dd>

**source:** `typing.Optional[LogSource]` — Filter by source (stdout, stderr, server)
    
</dd>
</dl>

<dl>
<dd>

**since:** `typing.Optional[datetime.datetime]` — Start timestamp filter (ISO 8601)
    
</dd>
</dl>

<dl>
<dd>

**until:** `typing.Optional[datetime.datetime]` — End timestamp filter (ISO 8601)
    
</dd>
</dl>

<dl>
<dd>

**search:** `typing.Optional[str]` — Full-text search in message (case-insensitive)
    
</dd>
</dl>

<dl>
<dd>

**after_id:** `typing.Optional[str]` — Return logs after this log_id (cursor-based pagination)
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Maximum number of results
    
</dd>
</dl>

<dl>
<dd>

**offset:** `typing.Optional[int]` — Number of results to skip
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.logs.<a href="src/terminaluse/logs/client.py">ingest_otlp</a>(...) -> OtlpLogIngestionResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Ingest OpenTelemetry logs from an agent. Requires agent API key authentication.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase, OtlpResourceLogs

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.logs.ingest_otlp(
    resource_logs=[
        OtlpResourceLogs()
    ],
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**resource_logs:** `typing.List[OtlpResourceLogs]` — Array of ResourceLogs per OTLP spec
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.logs.<a href="src/terminaluse/logs/client.py">stream</a>(...) -> typing.Iterator[bytes]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Stream logs for an agent in real-time using Server-Sent Events (SSE). Emits multiple event types (connected, log, error) discriminated by 'type' field. Only streams NEW logs after connection (like tail -f). Auto-disconnects after 5 minutes for cost control.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.logs.stream(
    agent_name="agent_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_name:** `str` — Name of the agent (format: namespace/name or agent ID)
    
</dd>
</dl>

<dl>
<dd>

**task_id:** `typing.Optional[str]` — Filter by task ID
    
</dd>
</dl>

<dl>
<dd>

**level:** `typing.Optional[LogLevel]` — Minimum log level
    
</dd>
</dl>

<dl>
<dd>

**source:** `typing.Optional[LogSource]` — Filter by source (stdout, stderr, server)
    
</dd>
</dl>

<dl>
<dd>

**branch_id:** `typing.Optional[str]` — Filter by branch/version ID
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Namespaces
<details><summary><code>client.namespaces.<a href="src/terminaluse/namespaces/client.py">list</a>(...) -> typing.List[Namespace]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List all namespaces the user has access to, optionally filtered by org.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.namespaces.list()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**org_id:** `typing.Optional[str]` — Filter by owner organization ID
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Maximum number of results
    
</dd>
</dl>

<dl>
<dd>

**page_number:** `typing.Optional[int]` — Page number
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.namespaces.<a href="src/terminaluse/namespaces/client.py">create</a>(...) -> Namespace</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Create a new namespace for multi-tenant isolation.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.namespaces.create(
    name="name",
    owner_org_id="owner_org_id",
    slug="slug",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` — Human-readable name.
    
</dd>
</dl>

<dl>
<dd>

**owner_org_id:** `str` — WorkOS organization ID that owns this namespace.
    
</dd>
</dl>

<dl>
<dd>

**slug:** `str` — URL-friendly unique identifier (lowercase alphanumeric and hyphens).
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.namespaces.<a href="src/terminaluse/namespaces/client.py">check_slug_availability</a>(...) -> SlugAvailabilityResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Check if a namespace slug is available for use.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.namespaces.check_slug_availability(
    slug="slug",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.namespaces.<a href="src/terminaluse/namespaces/client.py">retrieve_by_slug</a>(...) -> Namespace</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get a namespace by its slug.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.namespaces.retrieve_by_slug(
    slug="slug",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.namespaces.<a href="src/terminaluse/namespaces/client.py">retrieve</a>(...) -> Namespace</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get a namespace by ID.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.namespaces.retrieve(
    namespace_id="namespace_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.namespaces.<a href="src/terminaluse/namespaces/client.py">delete</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Delete a namespace (must be empty).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.namespaces.delete(
    namespace_id="namespace_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.namespaces.<a href="src/terminaluse/namespaces/client.py">update</a>(...) -> Namespace</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Update a namespace's properties.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.namespaces.update(
    namespace_id="namespace_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**name:** `typing.Optional[str]` — Human-readable name.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.namespaces.<a href="src/terminaluse/namespaces/client.py">retry_provisioning</a>(...) -> Namespace</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Retry provisioning for a namespace that failed or is stuck.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.namespaces.retry_provisioning(
    namespace_id="namespace_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**force:** `typing.Optional[bool]` — Force retry even if status is PENDING (for stuck namespaces)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Projects
<details><summary><code>client.projects.<a href="src/terminaluse/projects/client.py">list</a>(...) -> typing.List[ProjectListItem]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List all projects the user has access to.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.projects.list()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_id:** `typing.Optional[str]` — Filter by namespace ID
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Maximum number of results
    
</dd>
</dl>

<dl>
<dd>

**page_number:** `typing.Optional[int]` — Page number
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.projects.<a href="src/terminaluse/projects/client.py">create</a>(...) -> Project</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Create a new project within a namespace.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.projects.create(
    name="name",
    namespace_id="namespace_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` — Project name (unique within namespace).
    
</dd>
</dl>

<dl>
<dd>

**namespace_id:** `str` — The namespace this project belongs to.
    
</dd>
</dl>

<dl>
<dd>

**description:** `typing.Optional[str]` — Optional project description.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.projects.<a href="src/terminaluse/projects/client.py">retrieve</a>(...) -> Project</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get a project by ID.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.projects.retrieve(
    project_id="project_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**project_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.projects.<a href="src/terminaluse/projects/client.py">delete</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Delete a project (must be empty).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.projects.delete(
    project_id="project_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**project_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.projects.<a href="src/terminaluse/projects/client.py">update</a>(...) -> Project</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Update a project's properties.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.projects.update(
    project_id="project_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**project_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**description:** `typing.Optional[str]` — Optional project description.
    
</dd>
</dl>

<dl>
<dd>

**name:** `typing.Optional[str]` — Project name.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.projects.<a href="src/terminaluse/projects/client.py">list_collaborators</a>(...) -> ProjectCollaboratorsResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List explicit collaborator roles on a project.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.projects.list_collaborators(
    project_id="project_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**project_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.projects.<a href="src/terminaluse/projects/client.py">upsert_collaborator</a>(...) -> ProjectCollaboratorResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Create or update an explicit collaborator role on a project.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.projects.upsert_collaborator(
    project_id="project_id",
    member_id="member_id",
    role="discoverer",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**project_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**member_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**role:** `UpsertProjectCollaboratorRequestRole` — Role to assign.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.projects.<a href="src/terminaluse/projects/client.py">remove_collaborator</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Remove explicit collaborator role tuples from a project.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.projects.remove_collaborator(
    project_id="project_id",
    member_id="member_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**project_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**member_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## RawEvents
<details><summary><code>client.raw_events.<a href="src/terminaluse/raw_events/client.py">publish_raw_event</a>(...) -> PublishRawEventResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Publish a raw SDK event for transformation and streaming.

    This endpoint replaces the deprecated `/stream-events` endpoint.
    Events are transformed via SDK-specific adapters (based on `sdk_type` and `sdk_version`)
    and the resulting stream parts are published to Redis for real-time consumption.

    Messages that should be stored (e.g., AssistantMessage, UserMessage) are
    automatically persisted to MongoDB for later retrieval.

    **Supported SDK Types:**
    - `claude`: Claude Agent SDK messages (StreamEvent, AssistantMessage, etc.)
    - `codex`: Codex SDK thread events (`item.*`, `turn.*`, `thread.*`)
    - `terminal_use`: Direct UIMessage format (Vercel-compatible)

    **What gets stored:**
    - AssistantMessage, UserMessage, ResultMessage, SystemMessage

    **What does NOT get stored:**
    - StreamEvent (ephemeral streaming deltas)

    Requires `update` permission on the task.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.raw_events.publish_raw_event(
    raw_event={
        "key": "value"
    },
    sdk_type="sdk_type",
    sdk_version="sdk_version",
    task_id="task_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**raw_event:** `typing.Dict[str, typing.Any]` — The raw SDK event payload
    
</dd>
</dl>

<dl>
<dd>

**sdk_type:** `str` — SDK type identifier (e.g., 'claude', 'codex', 'terminal_use')
    
</dd>
</dl>

<dl>
<dd>

**sdk_version:** `str` — SDK version in semver format (e.g., '0.1.22')
    
</dd>
</dl>

<dl>
<dd>

**task_id:** `str` — Task ID to publish the event to
    
</dd>
</dl>

<dl>
<dd>

**idempotency_key:** `typing.Optional[str]` — Optional idempotency key for request-level deduplication
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Registry
<details><summary><code>client.registry.<a href="src/terminaluse/registry/client.py">auth</a>(...) -> RegistryAuthResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get short-lived credentials for pushing images to a namespace's registry.

    Each namespace has its own isolated registry repository. The token returned
    can ONLY push images to the specified namespace's repository.

    The CLI uses this endpoint to authenticate with Docker before pushing
    agent images. Returns a token valid for approximately 1 hour.

    **Usage with Docker:**
    ```bash
    docker login {registry_url} -u {username} -p {token}
    docker push {registry_url}/{repository}/{agent}:{tag}
    ```
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.registry.auth(
    namespace="acme",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace:** `str` — Target namespace slug for the image push
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Spans
<details><summary><code>client.spans.<a href="src/terminaluse/spans/client.py">list</a>(...) -> typing.List[Span]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List all spans for a given task.
Requires read permission on the task.
Optionally filter by trace_id within the task.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.spans.list(
    task_id="task_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `str` — The task ID
    
</dd>
</dl>

<dl>
<dd>

**trace_id:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` 
    
</dd>
</dl>

<dl>
<dd>

**page_number:** `typing.Optional[int]` 
    
</dd>
</dl>

<dl>
<dd>

**order_by:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**order_direction:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.spans.<a href="src/terminaluse/spans/client.py">create</a>(...) -> Span</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Create a new span with the provided parameters.
Requires update (edit) permission on the associated task.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase
import datetime

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.spans.create(
    name="name",
    start_time=datetime.datetime.fromisoformat("2024-01-15T09:30:00+00:00"),
    task_id="task_id",
    trace_id="trace_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` — Name that describes what operation this span represents
    
</dd>
</dl>

<dl>
<dd>

**start_time:** `datetime.datetime` — The time the span started
    
</dd>
</dl>

<dl>
<dd>

**task_id:** `str` — ID of the task this span is associated with, used for authorization
    
</dd>
</dl>

<dl>
<dd>

**trace_id:** `str` — Unique identifier for the trace this span belongs to
    
</dd>
</dl>

<dl>
<dd>

**data:** `typing.Optional[typing.Dict[str, typing.Any]]` — Any additional metadata or context for the span
    
</dd>
</dl>

<dl>
<dd>

**end_time:** `typing.Optional[datetime.datetime]` — The time the span ended
    
</dd>
</dl>

<dl>
<dd>

**id:** `typing.Optional[str]` — Unique identifier for the span. If not provided, an ID will be generated.
    
</dd>
</dl>

<dl>
<dd>

**input:** `typing.Optional[typing.Dict[str, typing.Any]]` — Input parameters or data for the operation
    
</dd>
</dl>

<dl>
<dd>

**output:** `typing.Optional[typing.Dict[str, typing.Any]]` — Output data resulting from the operation
    
</dd>
</dl>

<dl>
<dd>

**parent_id:** `typing.Optional[str]` — ID of the parent span if this is a child span in a trace
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.spans.<a href="src/terminaluse/spans/client.py">retrieve</a>(...) -> Span</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get a span by ID.
Requires read permission on the span's parent task.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.spans.retrieve(
    span_id="span_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**span_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.spans.<a href="src/terminaluse/spans/client.py">update</a>(...) -> Span</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Update a span with the provided output data and mark it as complete.
Requires update (edit) permission on the span's parent task.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.spans.update(
    span_id="span_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**span_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**data:** `typing.Optional[typing.Dict[str, typing.Any]]` — Any additional metadata or context for the span
    
</dd>
</dl>

<dl>
<dd>

**end_time:** `typing.Optional[datetime.datetime]` — The time the span ended
    
</dd>
</dl>

<dl>
<dd>

**input:** `typing.Optional[typing.Dict[str, typing.Any]]` — Input parameters or data for the operation
    
</dd>
</dl>

<dl>
<dd>

**name:** `typing.Optional[str]` — Name that describes what operation this span represents
    
</dd>
</dl>

<dl>
<dd>

**output:** `typing.Optional[typing.Dict[str, typing.Any]]` — Output data resulting from the operation
    
</dd>
</dl>

<dl>
<dd>

**parent_id:** `typing.Optional[str]` — ID of the parent span if this is a child span in a trace
    
</dd>
</dl>

<dl>
<dd>

**start_time:** `typing.Optional[datetime.datetime]` — The time the span started
    
</dd>
</dl>

<dl>
<dd>

**trace_id:** `typing.Optional[str]` — Unique identifier for the trace this span belongs to
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## States
<details><summary><code>client.states.<a href="src/terminaluse/states/client.py">list</a>(...) -> typing.List[State]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List all states, filtered by task_id or agent_id (at least one required).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.states.list()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `typing.Optional[str]` — Task ID
    
</dd>
</dl>

<dl>
<dd>

**agent_id:** `typing.Optional[str]` — Agent ID
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Limit
    
</dd>
</dl>

<dl>
<dd>

**page_number:** `typing.Optional[int]` — Page number
    
</dd>
</dl>

<dl>
<dd>

**order_by:** `typing.Optional[str]` — Field to order by
    
</dd>
</dl>

<dl>
<dd>

**order_direction:** `typing.Optional[str]` — Order direction (asc or desc)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.states.<a href="src/terminaluse/states/client.py">create</a>(...) -> State</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.states.create(
    agent_id="agent_id",
    state={
        "key": "value"
    },
    task_id="task_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**state:** `typing.Dict[str, typing.Any]` 
    
</dd>
</dl>

<dl>
<dd>

**task_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.states.<a href="src/terminaluse/states/client.py">retrieve</a>(...) -> State</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get a state by its unique state ID.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.states.retrieve(
    state_id="state_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**state_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.states.<a href="src/terminaluse/states/client.py">update</a>(...) -> State</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.states.update(
    state_id="state_id",
    agent_id="agent_id",
    state={
        "key": "value"
    },
    task_id="task_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**state_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**state:** `typing.Dict[str, typing.Any]` 
    
</dd>
</dl>

<dl>
<dd>

**task_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.states.<a href="src/terminaluse/states/client.py">delete</a>(...) -> State</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.states.delete(
    state_id="state_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**state_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Tasks
<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">list</a>(...) -> typing.List[TaskResponse]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List all tasks.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.list()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_id:** `typing.Optional[str]` — Optional agent filter. When provided, we authorize it via direct OpenFGA Check and avoid ListObjects(agent) to prevent false 403s from transient/partial list results.
    
</dd>
</dl>

<dl>
<dd>

**namespace_id:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**branch_id:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**status:** `typing.Optional[typing.Union[TaskStatus, typing.Sequence[TaskStatus]]]` 
    
</dd>
</dl>

<dl>
<dd>

**created_after:** `typing.Optional[datetime.datetime]` 
    
</dd>
</dl>

<dl>
<dd>

**created_before:** `typing.Optional[datetime.datetime]` 
    
</dd>
</dl>

<dl>
<dd>

**include_total:** `typing.Optional[bool]` 
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` 
    
</dd>
</dl>

<dl>
<dd>

**page_number:** `typing.Optional[int]` 
    
</dd>
</dl>

<dl>
<dd>

**order_by:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**order_direction:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**relationships:** `typing.Optional[typing.Union[TaskRelationships, typing.Sequence[TaskRelationships]]]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">create</a>(...) -> TaskResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Create a new task for an agent.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.create()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**agent_id:** `typing.Optional[str]` — Agent ID (provide this OR agent_name)
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `typing.Optional[str]` — Agent name as 'namespace/name' (provide this OR agent_id)
    
</dd>
</dl>

<dl>
<dd>

**branch:** `typing.Optional[str]` — Target branch for version routing
    
</dd>
</dl>

<dl>
<dd>

**filesystem_id:** `typing.Optional[str]` — Existing filesystem ID
    
</dd>
</dl>

<dl>
<dd>

**name:** `typing.Optional[str]` — Task name
    
</dd>
</dl>

<dl>
<dd>

**params:** `typing.Optional[typing.Dict[str, typing.Any]]` — Task parameters
    
</dd>
</dl>

<dl>
<dd>

**project_id:** `typing.Optional[str]` — Project ID for new filesystem
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">migrate</a>(...) -> MigrateTasksResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Migrate tasks between versions within the same branch. Supports two modes: bulk migration by source version (from_version_id), or migration of specific tasks (task_ids). Target can be explicit (to_version_id) or latest active version (to_latest).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.migrate()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**from_version_id:** `typing.Optional[str]` — Migrate ALL RUNNING tasks from this version
    
</dd>
</dl>

<dl>
<dd>

**task_ids:** `typing.Optional[typing.List[str]]` — OR migrate specific task IDs
    
</dd>
</dl>

<dl>
<dd>

**to_latest:** `typing.Optional[bool]` — OR migrate to ACTIVE/DEPLOYING version on branch
    
</dd>
</dl>

<dl>
<dd>

**to_version_id:** `typing.Optional[str]` — Explicit target version ID
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">retrieve_by_name</a>(...) -> TaskResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get a task by its unique name.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.retrieve_by_name(
    task_name="task_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**relationships:** `typing.Optional[typing.Union[TaskRelationships, typing.Sequence[TaskRelationships]]]` 
    
</dd>
</dl>

<dl>
<dd>

**agent_id:** `typing.Optional[str]` — Optional agent filter. When provided, we authorize it via direct OpenFGA Check and avoid ListObjects(agent) to prevent false 403s from transient/partial list results.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">update_by_name</a>(...) -> Task</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Update mutable fields for a task by its unique Name.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.update_by_name(
    task_name="task_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request:** `UpdateTaskRequest` 
    
</dd>
</dl>

<dl>
<dd>

**agent_id:** `typing.Optional[str]` — Optional agent filter. When provided, we authorize it via direct OpenFGA Check and avoid ListObjects(agent) to prevent false 403s from transient/partial list results.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">delete_by_name</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Delete a task by its unique name.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.delete_by_name(
    task_name="task_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_id:** `typing.Optional[str]` — Optional agent filter. When provided, we authorize it via direct OpenFGA Check and avoid ListObjects(agent) to prevent false 403s from transient/partial list results.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">stream_by_name</a>(...) -> typing.Iterator[bytes]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Stream events for a task by its unique name using Server-Sent Events (SSE).

    Supports automatic reconnection with Last-Event-ID header. When the client
    reconnects, it sends the Last-Event-ID header with the last received event ID,
    and the server resumes from that point.

    Returns TextStreamPart events (Vercel AI SDK compatible format).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.stream_by_name(
    task_name="task_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_id:** `typing.Optional[str]` — Optional agent filter. When provided, we authorize it via direct OpenFGA Check and avoid ListObjects(agent) to prevent false 403s from transient/partial list results.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">retrieve</a>(...) -> TaskResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get a task by its unique ID.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.retrieve(
    task_id="task_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**relationships:** `typing.Optional[typing.Union[TaskRelationships, typing.Sequence[TaskRelationships]]]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">update</a>(...) -> Task</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Update mutable fields for a task by its unique ID.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.update(
    task_id="task_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request:** `UpdateTaskRequest` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">delete</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Delete a task by its unique ID.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.delete(
    task_id="task_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">cancel</a>(...) -> TaskResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Cancel a running task.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.cancel(
    task_id="task_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">send_event</a>(...) -> Event</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Send an event to a running task.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.send_event(
    task_id="task_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**content:** `typing.Optional[CreateTaskEventRequestContent]` — Event content
    
</dd>
</dl>

<dl>
<dd>

**idempotency_key:** `typing.Optional[str]` — Optional idempotency key for retry-safe event delivery.
    
</dd>
</dl>

<dl>
<dd>

**persist_message:** `typing.Optional[bool]` — Whether to also create a message record for this event. Defaults to True.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">handler_end</a>(...) -> HandlerEndResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Signal that an ACP handler has finished processing an event.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.handler_end(
    task_id="task_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**duration_ms:** `typing.Optional[int]` 
    
</dd>
</dl>

<dl>
<dd>

**error:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**event_id:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**pod_id:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**success:** `typing.Optional[bool]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">stream</a>(...) -> typing.Iterator[bytes]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Stream events for a task by its unique ID using Server-Sent Events (SSE).

    Supports automatic reconnection with Last-Event-ID header. When the client
    reconnects, it sends the Last-Event-ID header with the last received event ID,
    and the server resumes from that point.

    Returns TextStreamPart events (Vercel AI SDK compatible format).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.stream(
    task_id="task_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">list_system_folder_types</a>(...) -> typing.List[SystemFolderTypeResponse]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get all registered system folder types with their configurations for a task.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.list_system_folder_types(
    task_id="task_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">get_system_folder</a>(...) -> typing.Optional[SystemFolderResponse]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get a task's system folder record by type.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.get_system_folder(
    task_id="task_id",
    folder_type="dot_claude",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**folder_type:** `SystemFolderType` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">get_system_folder_download_url</a>(...) -> typing.Optional[PresignedUrlResponse]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get a presigned URL for direct download of a system folder archive from GCS.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase, PresignedUrlRequest

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.get_system_folder_download_url(
    task_id="task_id",
    folder_type="dot_claude",
    request=PresignedUrlRequest(),
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**folder_type:** `SystemFolderType` 
    
</dd>
</dl>

<dl>
<dd>

**request:** `typing.Optional[PresignedUrlRequest]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">system_folder_sync_complete</a>(...) -> SystemFolderSyncCompleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Complete a system folder sync operation and update metadata.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.system_folder_sync_complete(
    task_id="task_id",
    folder_type="dot_claude",
    direction="direction",
    status="status",
    sync_id="sync_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**folder_type:** `SystemFolderType` 
    
</dd>
</dl>

<dl>
<dd>

**direction:** `str` — Sync direction: 'UP' or 'DOWN'.
    
</dd>
</dl>

<dl>
<dd>

**status:** `str` — Sync status: 'SUCCESS' or 'FAILED'.
    
</dd>
</dl>

<dl>
<dd>

**sync_id:** `str` — Unique ID for this sync operation (idempotency key).
    
</dd>
</dl>

<dl>
<dd>

**archive_checksum:** `typing.Optional[str]` — SHA256 checksum of the archive.
    
</dd>
</dl>

<dl>
<dd>

**archive_size_bytes:** `typing.Optional[int]` — Size of the archive in bytes.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tasks.<a href="src/terminaluse/tasks/client.py">get_system_folder_upload_url</a>(...) -> PresignedUrlResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get a presigned URL for direct upload of a system folder archive to GCS.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase, PresignedUrlRequest

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tasks.get_system_folder_upload_url(
    task_id="task_id",
    folder_type="dot_claude",
    request=PresignedUrlRequest(),
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**folder_type:** `SystemFolderType` 
    
</dd>
</dl>

<dl>
<dd>

**request:** `typing.Optional[PresignedUrlRequest]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Tracker
<details><summary><code>client.tracker.<a href="src/terminaluse/tracker/client.py">list</a>(...) -> typing.List[AgentTaskTracker]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List agent task trackers for a task, optionally filtered by agent.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tracker.list(
    task_id="task_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `str` — The task ID
    
</dd>
</dl>

<dl>
<dd>

**agent_id:** `typing.Optional[str]` — Agent ID
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Limit
    
</dd>
</dl>

<dl>
<dd>

**page_number:** `typing.Optional[int]` — Page number
    
</dd>
</dl>

<dl>
<dd>

**order_by:** `typing.Optional[str]` — Field to order by
    
</dd>
</dl>

<dl>
<dd>

**order_direction:** `typing.Optional[str]` — Order direction (asc or desc)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tracker.<a href="src/terminaluse/tracker/client.py">retrieve</a>(...) -> AgentTaskTracker</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get agent task tracker by tracker ID
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tracker.retrieve(
    tracker_id="tracker_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**tracker_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tracker.<a href="src/terminaluse/tracker/client.py">update</a>(...) -> AgentTaskTracker</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Update agent task tracker by tracker ID
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tracker.update(
    tracker_id="tracker_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**tracker_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**last_processed_event_id:** `typing.Optional[str]` — The most recent processed event ID (omit to leave unchanged)
    
</dd>
</dl>

<dl>
<dd>

**status:** `typing.Optional[str]` — Processing status
    
</dd>
</dl>

<dl>
<dd>

**status_reason:** `typing.Optional[str]` — Optional status reason
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## CliAuthentication
<details><summary><code>client.cli_authentication.<a href="src/terminaluse/cli_authentication/client.py">refresh_cli_token</a>(...) -> CliRefreshResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Refresh an expired session JWT using a refresh token.

Note: Refresh tokens are single-use. The response contains a new refresh_token
that must replace the old one for future refresh operations.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.cli_authentication.refresh_cli_token(
    refresh_token="refresh_token",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**refresh_token:** `str` — Refresh token from previous authentication
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.cli_authentication.<a href="src/terminaluse/cli_authentication/client.py">exchange_cli_token</a>(...) -> CliTokenResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Exchange authorization code for session JWT using PKCE.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.cli_authentication.exchange_cli_token(
    code="code",
    code_verifier="code_verifier",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**code:** `str` — Authorization code from OAuth callback
    
</dd>
</dl>

<dl>
<dd>

**code_verifier:** `str` — PKCE code verifier
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Authentication
<details><summary><code>client.authentication.<a href="src/terminaluse/authentication/client.py">authenticate</a>() -> PrincipalContextEntity</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Validate a WorkOS JWT and return the principal context.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.authentication.authenticate()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## OAuth
<details><summary><code>client.o_auth.<a href="src/terminaluse/o_auth/client.py">initiate_oauth</a>(...) -> OAuthInitiateResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Generate authorization URL for OAuth authentication.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.o_auth.initiate_oauth(
    redirect_uri="redirect_uri",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**redirect_uri:** `str` — URI to redirect after authentication
    
</dd>
</dl>

<dl>
<dd>

**code_challenge:** `typing.Optional[str]` — PKCE code challenge (S256)
    
</dd>
</dl>

<dl>
<dd>

**connection_id:** `typing.Optional[str]` — Optional WorkOS connection ID for SSO
    
</dd>
</dl>

<dl>
<dd>

**organization_id:** `typing.Optional[str]` — Organization ID to scope the authentication to
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.o_auth.<a href="src/terminaluse/o_auth/client.py">exchange_token</a>(...) -> OAuthTokenResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Exchange authorization code for access token.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.o_auth.exchange_token(
    code="code",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**code:** `str` — Authorization code from OAuth callback
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Organizations
<details><summary><code>client.organizations.<a href="src/terminaluse/organizations/client.py">list</a>() -> typing.List[OrganizationResponse]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List all organizations the current user belongs to.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.organizations.list()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.organizations.<a href="src/terminaluse/organizations/client.py">retrieve_current</a>() -> OrganizationResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get the current user's organization info.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.organizations.retrieve_current()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.organizations.<a href="src/terminaluse/organizations/client.py">list_invitations</a>() -> typing.List[OrganizationInvitationResponse]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List pending invitations for the current organization.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.organizations.list_invitations()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.organizations.<a href="src/terminaluse/organizations/client.py">create_invitation</a>(...) -> CreateOrganizationInvitationResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Invite a user to the current organization. Idempotent for existing pending invites by email.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.organizations.create_invitation(
    email="email",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**email:** `str` — Invitee email
    
</dd>
</dl>

<dl>
<dd>

**role_slug:** `typing.Optional[CreateOrganizationInvitationRequestRoleSlug]` — Organization role slug for the invited member
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.organizations.<a href="src/terminaluse/organizations/client.py">revoke_invitation</a>(...) -> OrganizationInvitationResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Revoke a pending invitation in the current organization.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.organizations.revoke_invitation(
    invitation_id="invitation_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**invitation_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.organizations.<a href="src/terminaluse/organizations/client.py">resend_invitation</a>(...) -> OrganizationInvitationResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Resend a pending invitation in the current organization.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.organizations.resend_invitation(
    invitation_id="invitation_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**invitation_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.organizations.<a href="src/terminaluse/organizations/client.py">list_members</a>() -> typing.List[OrganizationMemberResponse]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List active members in the current organization.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.organizations.list_members()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.organizations.<a href="src/terminaluse/organizations/client.py">update_member</a>(...) -> OrganizationMemberResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Update a member role in the current organization.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.organizations.update_member(
    membership_id="membership_id",
    role_slug="admin",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**membership_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**role_slug:** `UpdateOrganizationMemberRequestRoleSlug` — Organization role slug for the target member
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.organizations.<a href="src/terminaluse/organizations/client.py">remove_member</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Remove an active member from the current organization.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.organizations.remove_member(
    membership_id="membership_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**membership_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## MessagesV2
<details><summary><code>client.messages_v2.<a href="src/terminaluse/messages_v2/client.py">list</a>(...) -> ListMessagesV2Response</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List messages for a task in Vercel AI SDK UIMessage format.

    This endpoint returns messages transformed from raw SDK events into
    a normalized UIMessage format suitable for frontend consumption.

    Features:
    - Tool merging: tool_use and tool_result are combined into single tool parts
    - Complete-units pagination: Never splits tool request/result pairs across pages
    - Runtime transformation: Raw SDK messages are transformed on-demand

    Args:
        task_id: The task ID to filter messages by
        limit: Maximum number of complete messages to return (default: 50)
        cursor: Opaque cursor string for pagination
        direction: Pagination direction - "older" (default) or "newer"
        parent_tool_use_id: Filter messages by parent tool use ID (for subagent context)

    Returns:
        ListMessagesV2Response with UIMessages and pagination info
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.messages_v2.list(
    task_id="task_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_id:** `str` — The task ID
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` 
    
</dd>
</dl>

<dl>
<dd>

**cursor:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**direction:** `typing.Optional[MessagesV2ListRequestDirection]` 
    
</dd>
</dl>

<dl>
<dd>

**parent_tool_use_id:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.messages_v2.<a href="src/terminaluse/messages_v2/client.py">retrieve</a>(...) -> typing.Optional[UiMessage]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get a single message by ID in UIMessage format.

    Returns the transformed UIMessage or null if not found.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.messages_v2.retrieve(
    message_id="message_id",
    task_id="task_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**message_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**task_id:** `str` — The task ID
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Versions
<details><summary><code>client.versions.<a href="src/terminaluse/versions/client.py">register</a>(...) -> RegisterContainerResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Register an agent container that has started up.

    Called by the agent container on startup to:
    1. Register its ACP URL with the platform
    2. Receive its API key for authenticating subsequent requests

    This endpoint should be called from within the container's entrypoint
    after the ACP server is ready to receive traffic.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.versions.register(
    acp_url="acp_url",
    branch_id="branch_id",
    version_id="version_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**acp_url:** `str` — ACP server URL (e.g., 'http://agent-main-abc123.agents.svc.cluster.local:8000')
    
</dd>
</dl>

<dl>
<dd>

**branch_id:** `str` — Branch ID
    
</dd>
</dl>

<dl>
<dd>

**version_id:** `str` — Version ID being registered
    
</dd>
</dl>

<dl>
<dd>

**registration_token:** `typing.Optional[str]` — Single-use registration token provided during deployment (required when configured)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.versions.<a href="src/terminaluse/versions/client.py">retrieve</a>(...) -> VersionResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get version details by ID.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.versions.retrieve(
    version_id="version_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**version_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.versions.<a href="src/terminaluse/versions/client.py">deploy_stream</a>(...) -> typing.Iterator[bytes]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

SSE endpoint for real-time deployment progress events.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.versions.deploy_stream(
    version_id="version_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**version_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.versions.<a href="src/terminaluse/versions/client.py">metrics</a>(...) -> VersionMetricsResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get deployment metrics for a specific version.

    Returns metrics related to the deployment process for this version,
    including average and P95 deployment durations queried from ClickHouse traces.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.versions.metrics(
    version_id="version_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**version_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.versions.<a href="src/terminaluse/versions/client.py">pod_logs</a>(...) -> VersionPodLogsResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get Kubernetes pod/container logs for a specific deployment version.

    Data is sourced from ClickHouse `otel.pod_logs`, populated by the dedicated
    pod-log collector DaemonSet. This endpoint has no Kubernetes or event-snapshot
    fallback path.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.versions.pod_logs(
    version_id="version_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**version_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**pod:** `typing.Optional[str]` — Filter by pod name
    
</dd>
</dl>

<dl>
<dd>

**container:** `typing.Optional[str]` — Filter by container name
    
</dd>
</dl>

<dl>
<dd>

**stream:** `typing.Optional[str]` — Filter by log stream (stdout/stderr)
    
</dd>
</dl>

<dl>
<dd>

**since:** `typing.Optional[datetime.datetime]` — Start timestamp filter (ISO 8601)
    
</dd>
</dl>

<dl>
<dd>

**until:** `typing.Optional[datetime.datetime]` — End timestamp filter (ISO 8601)
    
</dd>
</dl>

<dl>
<dd>

**search:** `typing.Optional[str]` — Full-text search in log message
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Maximum number of results
    
</dd>
</dl>

<dl>
<dd>

**after:** `typing.Optional[str]` — Cursor for the next page, using the previous log_id
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.versions.<a href="src/terminaluse/versions/client.py">pod_metrics</a>(...) -> VersionPodMetricsResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get pod-level resource metrics (CPU and memory) for a specific version.

    Data is sourced from ClickHouse `otel_metrics_*` tables populated by the
    OpenTelemetry Collector's Prometheus receiver scraping kubelet cAdvisor metrics.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.versions.pod_metrics(
    version_id="version_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**version_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**window_minutes:** `typing.Optional[int]` 
    
</dd>
</dl>

<dl>
<dd>

**step_seconds:** `typing.Optional[int]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## VersionEvents
<details><summary><code>client.version_events.<a href="src/terminaluse/version_events/client.py">versions_events_list</a>(...) -> VersionEventListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List lifecycle events for a version. Events are ordered by sequence_id.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.version_events.versions_events_list(
    version_id="version_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**version_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**event_type:** `typing.Optional[VersionEventType]` — Filter by event type
    
</dd>
</dl>

<dl>
<dd>

**after_sequence_id:** `typing.Optional[int]` — Return events after this sequence_id (for ascending pagination)
    
</dd>
</dl>

<dl>
<dd>

**before_sequence_id:** `typing.Optional[int]` — Return events before this sequence_id (for descending pagination)
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Maximum events to return
    
</dd>
</dl>

<dl>
<dd>

**descending:** `typing.Optional[bool]` — Order by sequence_id descending (newest first)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Agents Branches
<details><summary><code>client.agents.branches.<a href="src/terminaluse/agents/branches/client.py">retrieve</a>(...) -> BranchResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get a specific branch by agent name and git branch.

    The git branch name will be normalized (lowercased, slashes converted to hyphens).
    For example, "feature/new-tool" becomes "feature-new-tool".
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.branches.retrieve(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
    branch="branch",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**branch:** `str` — Target branch (e.g., 'main', 'feature/login')
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.branches.<a href="src/terminaluse/agents/branches/client.py">list</a>(...) -> BranchListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List all branches for an agent.

    Each branch represents a git branch (e.g., main, staging, feature-x).
    By default, retired branches are excluded.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.branches.list(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**include_retired:** `typing.Optional[bool]` — Include retired branches in results
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.branches.<a href="src/terminaluse/agents/branches/client.py">rollback</a>(...) -> RollbackResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Roll back a branch to a previous version by namespace, agent, and git branch name.

    Key behavior:
    - EnvVar table is NOT modified (remains pending state)
    - Uses Version.secrets_snapshot as deployed state
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.branches.rollback(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
    branch="branch",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**branch:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request:** `RollbackRequest` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Agents Environments
<details><summary><code>client.agents.environments.<a href="src/terminaluse/agents/environments/client.py">list</a>(...) -> EnvListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List all environments for an agent.

    Environments define deployment targets (e.g., production, staging, preview).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.environments.list(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.environments.<a href="src/terminaluse/agents/environments/client.py">create</a>(...) -> EnvResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Create a new environment for an agent.

    Environments define deployment targets with branch matching rules.
    The is_prod flag cannot be set via API - production environment is protected.

    **Branch Rules:**
    - Exact match: ["main"] or ["develop"]
    - Wildcard: ["feature/*"] matches feature/foo, feature/bar
    - Catch-all: ["*"] matches any branch
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.environments.create(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
    branch_rules=[
        "branch_rules"
    ],
    name="name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**branch_rules:** `typing.List[str]` — Branch patterns for matching (e.g., ['feature/*'], ['develop'])
    
</dd>
</dl>

<dl>
<dd>

**name:** `str` — Environment name (lowercase alphanumeric and hyphens only)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.environments.<a href="src/terminaluse/agents/environments/client.py">retrieve</a>(...) -> EnvResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get environment details by name.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.environments.retrieve(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
    env_name="env_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**env_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.environments.<a href="src/terminaluse/agents/environments/client.py">update</a>(...) -> EnvResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Update an existing environment.

    All fields are optional - only provided fields will be updated.

    **Production Environment Constraints:**
    - branch_rules must be exactly one literal string (no wildcards)
    - is_prod cannot be changed via API
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.environments.update(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
    env_name="env_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**env_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**branch_rules:** `typing.Optional[typing.List[str]]` — Branch patterns for matching
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.environments.<a href="src/terminaluse/agents/environments/client.py">delete</a>(...) -> DeleteEnvResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Delete an environment.

    **Note:** Production environments (is_prod=True) cannot be deleted.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.environments.delete(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
    env_name="env_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**env_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.environments.<a href="src/terminaluse/agents/environments/client.py">resolve_env</a>(...) -> ResolveEnvResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Resolve which environment matches a given branch.

    Uses specificity-based matching:
    - Exact match wins over wildcards (e.g., "main" matches production before preview)
    - Prefix wildcards match by length (e.g., "feature/*" beats "*")
    - Catch-all "*" has lowest priority

    Returns 404 if no environment matches the branch.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.environments.resolve_env(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
    branch="branch",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**branch:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Agents Secrets
<details><summary><code>client.agents.secrets.<a href="src/terminaluse/agents/secrets/client.py">list</a>(...) -> CrossEnvSecretsListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Cross-environment view of all secrets for an agent.

    Shows which keys exist in which environments.
    Never returns actual secret values (is_secret=True).
    Values for non-secrets only returned when include_values=True.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.secrets.list(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**include_values:** `typing.Optional[bool]` — Include values for non-secrets (is_secret=False only)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Agents Versions
<details><summary><code>client.agents.versions.<a href="src/terminaluse/agents/versions/client.py">list</a>(...) -> VersionListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List all versions for an agent.

    Optionally filter by branch name or version status.
    Versions are ordered by deployed_at descending (most recent first).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.versions.list(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**branch:** `typing.Optional[str]` — Filter by branch name (e.g., 'main', 'feature/login'). If not provided, returns versions across all branches.
    
</dd>
</dl>

<dl>
<dd>

**status:** `typing.Optional[VersionStatus]` — Filter by version status
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Maximum versions to return
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Agents Environments Branches
<details><summary><code>client.agents.environments.branches.<a href="src/terminaluse/agents/environments/branches/client.py">list</a>(...) -> BranchListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List all branches that match this environment's branch rules.

    For wildcard environments (like preview with ["*"]),
    returns all non-retired branches for the agent.

    For specific branch rules (like production with ["main"]),
    returns only the matching branch(es).

    Branches are sorted by updated_at descending (most recent first).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.environments.branches.list(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
    env_name="env_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**env_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Agents Environments Secrets
<details><summary><code>client.agents.environments.secrets.<a href="src/terminaluse/agents/environments/secrets/client.py">list</a>(...) -> EnvVarListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List PENDING secrets for an environment (from EnvVar table).

    This is what will be used on next deploy.
    For deployed state, use GET /agents/{namespace_slug}/{agent_name}/environments/{env}/secrets/deployed

    Note: is_secret=True values are NEVER returned, only non-secrets when include_values=True.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.environments.secrets.list(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
    env_name="env_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**env_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**include_values:** `typing.Optional[bool]` — Include values for non-secrets (is_secret=False only)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.environments.secrets.<a href="src/terminaluse/agents/environments/secrets/client.py">set</a>(...) -> SetEnvVarResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Set one or more secrets/config values.

    If redeploy=True (default) and environment has active deployment,
    triggers redeploy with same image but new secrets_snapshot.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase, EnvVarValue

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.environments.secrets.set(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
    env_name="env_name",
    secrets={
        "key": EnvVarValue(
            value="value",
        )
    },
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**env_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**secrets:** `typing.Dict[str, EnvVarValue]` — Dict of {key: {value, is_secret}} to set
    
</dd>
</dl>

<dl>
<dd>

**redeploy:** `typing.Optional[bool]` — If true and env has active deployment, trigger redeploy with new secrets
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.environments.secrets.<a href="src/terminaluse/agents/environments/secrets/client.py">list_deployed</a>(...) -> DeployedSecretsResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List DEPLOYED secrets for an environment (from Version.secrets_snapshot).

    This is what's currently running. May differ from pending state after rollback.
    Only returns keys, never actual values.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.environments.secrets.list_deployed(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
    env_name="env_name",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**env_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agents.environments.secrets.<a href="src/terminaluse/agents/environments/secrets/client.py">delete</a>(...) -> DeleteEnvVarResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Delete a secret from an environment.

    If redeploy=True (default), triggers redeploy with updated secrets.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.agents.environments.secrets.delete(
    namespace_slug="namespace_slug",
    agent_name="agent_name",
    env_name="env_name",
    key="key",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**namespace_slug:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**agent_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**env_name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**key:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**redeploy:** `typing.Optional[bool]` — If true, trigger redeploy after deletion
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Branches Events
<details><summary><code>client.branches.events.<a href="src/terminaluse/branches/events/client.py">list</a>(...) -> VersionEventListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List lifecycle events across all versions for a branch.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.branches.events.list(
    branch_id="branch_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**branch_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**event_type:** `typing.Optional[VersionEventType]` — Filter by event type
    
</dd>
</dl>

<dl>
<dd>

**after_sequence_id:** `typing.Optional[int]` — Return events after this sequence_id (for ascending pagination)
    
</dd>
</dl>

<dl>
<dd>

**before_sequence_id:** `typing.Optional[int]` — Return events before this sequence_id (for descending pagination)
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Maximum events to return
    
</dd>
</dl>

<dl>
<dd>

**descending:** `typing.Optional[bool]` — Order by sequence_id descending (newest first)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Branches Versions
<details><summary><code>client.branches.versions.<a href="src/terminaluse/branches/versions/client.py">list</a>(...) -> VersionListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List all versions for a branch.

    Versions are ordered by deployed_at descending (most recent first).
    Each version represents a git commit that was deployed.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUseBase

client = TerminalUseBase(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.branches.versions.list(
    branch_id="branch_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**branch_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Maximum versions to return
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

