# Reference
## Telemetry
<details><summary><code>client.telemetry.<a href="src/terminaluse/telemetry/client.py">agent_metrics_ingest</a>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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.Sequence[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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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.Sequence[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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[CreateApiKeyResponse]</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[typing.List[Agent]]</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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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 (currently accepts slug)
    
</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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

**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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

## Schedules
<details><summary><code>client.schedules.<a href="src/terminaluse/schedules/client.py">agents_schedules_list</a>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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[dt.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[dt.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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 PauseScheduleRequest, TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse, UnpauseScheduleRequest

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

**target_version_id:** `typing.Optional[str]` — Version ID to rollback to (defaults to previous version if not specified)
    
</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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

**target_version_id:** `typing.Optional[str]` — Version ID to rollback to (defaults to previous version if not specified)
    
</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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 ApiKeyScope, TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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="viewer",
        )
    ],
)

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

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

<dl>
<dd>

**scopes:** `typing.Sequence[ApiKeyScope]` — List of resource scopes. At least one scope is required.
    
</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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

## Events
<details><summary><code>client.events.<a href="src/terminaluse/events/client.py">list</a>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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 to filter events by
    
</dd>
</dl>

<dl>
<dd>

**agent_id:** `str` — The agent ID to filter events by
    
</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>(...) -&gt; AsyncHttpResponse[Event]</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>() -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.filesystems.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.filesystems.<a href="src/terminaluse/filesystems/client.py">create</a>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 PresignedUrlRequest, TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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">list_files</a>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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.Sequence[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>(...) -&gt; AsyncHttpResponse[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 PresignedUrlRequest, TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

## Logs
<details><summary><code>client.logs.<a href="src/terminaluse/logs/client.py">list</a>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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[dt.datetime]` — Start timestamp filter (ISO 8601)
    
</dd>
</dl>

<dl>
<dd>

**until:** `typing.Optional[dt.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>(...) -&gt; AsyncHttpResponse[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 OtlpResourceLogs, TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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.Sequence[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>

## Messages
<details><summary><code>client.messages.<a href="src/terminaluse/messages/client.py">list</a>(...) -&gt; AsyncHttpResponse[typing.List[TaskMessage]]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List messages for a task with offset-based pagination.

For cursor-based pagination with infinite scroll support, use /messages/paginated.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.messages.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>

**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.messages.<a href="src/terminaluse/messages/client.py">create</a>(...) -&gt; AsyncHttpResponse[TaskMessage]</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TaskMessageContent_ClaudeMessage, TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.messages.create(
    content=TaskMessageContent_ClaudeMessage(
        author="user",
        message_type="message_type",
        raw_message={"key": "value"},
    ),
    task_id="task_id",
)

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**content:** `TaskMessageContent` 
    
</dd>
</dl>

<dl>
<dd>

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

<dl>
<dd>

**streaming_status:** `typing.Optional[CreateTaskMessageRequestStreamingStatus]` 
    
</dd>
</dl>

<dl>
<dd>

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


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

<details><summary><code>client.messages.<a href="src/terminaluse/messages/client.py">list_paginated</a>(...) -&gt; AsyncHttpResponse[PaginatedMessagesResponse]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List messages for a task with cursor-based pagination.

This endpoint is designed for infinite scroll UIs where new messages may arrive
while paginating through older ones.

Args:
    task_id: The task ID to filter messages by
    limit: Maximum number of messages to return (default: 50)
    cursor: Opaque cursor string for pagination. Pass the `next_cursor` from
            a previous response to get the next page.
    direction: Pagination direction - "older" to get older messages (default),
               "newer" to get newer messages.

Returns:
    PaginatedMessagesResponse with:
    - data: List of messages (newest first when direction="older")
    - next_cursor: Cursor for fetching the next page (null if no more pages)
    - has_more: Whether there are more messages to fetch

Example:
    First request: GET /messages/paginated?task_id=xxx&limit=50
    Next page: GET /messages/paginated?task_id=xxx&limit=50&cursor=<next_cursor>
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.messages.list_paginated(
    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[MessagesListPaginatedRequestDirection]` 
    
</dd>
</dl>

<dl>
<dd>

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


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

<details><summary><code>client.messages.<a href="src/terminaluse/messages/client.py">retrieve</a>(...) -&gt; AsyncHttpResponse[TaskMessage]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Get a message by ID. Authorization is derived from the message's parent task.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.messages.retrieve(
    message_id="message_id",
)

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**message_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.messages.<a href="src/terminaluse/messages/client.py">update</a>(...) -&gt; AsyncHttpResponse[TaskMessage]</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TaskMessageContent_ClaudeMessage, TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.messages.update(
    message_id="message_id",
    content=TaskMessageContent_ClaudeMessage(
        author="user",
        message_type="message_type",
        raw_message={"key": "value"},
    ),
    task_id="task_id",
)

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

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

<dl>
<dd>

**content:** `TaskMessageContent` 
    
</dd>
</dl>

<dl>
<dd>

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

<dl>
<dd>

**streaming_status:** `typing.Optional[UpdateTaskMessageRequestStreamingStatus]` 
    
</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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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, hyphens, underscores).
    
</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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

**gcp_sa_email:** `typing.Optional[str]` — GCP service account email (set by infra).
    
</dd>
</dl>

<dl>
<dd>

**gcs_bucket:** `typing.Optional[str]` — GCS bucket name (set by infra).
    
</dd>
</dl>

<dl>
<dd>

**k8s_namespace:** `typing.Optional[str]` — K8s namespace name (set by infra).
    
</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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[typing.List[Project]]</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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

## Registry
<details><summary><code>client.registry.<a href="src/terminaluse/registry/client.py">auth</a>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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
import datetime

from terminaluse import TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.spans.create(
    name="name",
    start_time=datetime.datetime.fromisoformat(
        "2024-01-15 09: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:** `dt.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[dt.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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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[dt.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[dt.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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[State]</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[State]</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[State]</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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]` 
    
</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>

**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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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.Sequence[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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

**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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

**task_metadata:** `typing.Optional[typing.Dict[str, typing.Any]]` 
    
</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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

**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>(...) -&gt; typing.AsyncIterator[AsyncHttpResponse[typing.AsyncIterator[typing.Any]]]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Stream events for a task by its unique name.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
response = client.tasks.stream_by_name(
    task_name="task_name",
)
for chunk in response.data:
    yield chunk

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**task_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.tasks.<a href="src/terminaluse/tasks/client.py">retrieve</a>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

**task_metadata:** `typing.Optional[typing.Dict[str, typing.Any]]` 
    
</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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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[TaskMessageContent]` — Event content
    
</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">stream</a>(...) -&gt; typing.AsyncIterator[AsyncHttpResponse[typing.AsyncIterator[typing.Any]]]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Stream events for a task by its unique ID.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
response = client.tasks.stream(
    task_id="task_id",
)
for chunk in response.data:
    yield chunk

```
</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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 PresignedUrlRequest, TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 PresignedUrlRequest, TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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` — Task ID (required for authorization)
    
</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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>() -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

## AuthorizationInternal
<details><summary><code>client.authorization_internal.<a href="src/terminaluse/authorization_internal/client.py">check_permission</a>(...) -&gt; AsyncHttpResponse[typing.Dict[str, typing.Any]]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Check if a principal has permission to perform an operation on a resource.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import PrincipalRequest, TerminalUse, TerminalUseResource

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.authorization_internal.check_permission(
    operation="create",
    principal=PrincipalRequest(
        member_id="member_id",
    ),
    resource=TerminalUseResource(
        selector="selector",
        type="member",
    ),
)

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**operation:** `AuthorizedOperationType` 
    
</dd>
</dl>

<dl>
<dd>

**principal:** `PrincipalRequest` 
    
</dd>
</dl>

<dl>
<dd>

**resource:** `TerminalUseResource` 
    
</dd>
</dl>

<dl>
<dd>

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


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

<details><summary><code>client.authorization_internal.<a href="src/terminaluse/authorization_internal/client.py">grant_permission</a>(...) -&gt; AsyncHttpResponse[typing.Dict[str, typing.Any]]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Grant a permission to a principal for a resource.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import PrincipalRequest, TerminalUse, TerminalUseResource

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.authorization_internal.grant_permission(
    operation="create",
    principal=PrincipalRequest(
        member_id="member_id",
    ),
    resource=TerminalUseResource(
        selector="selector",
        type="member",
    ),
)

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**operation:** `AuthorizedOperationType` 
    
</dd>
</dl>

<dl>
<dd>

**principal:** `PrincipalRequest` 
    
</dd>
</dl>

<dl>
<dd>

**resource:** `TerminalUseResource` 
    
</dd>
</dl>

<dl>
<dd>

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


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

<details><summary><code>client.authorization_internal.<a href="src/terminaluse/authorization_internal/client.py">revoke_permission</a>(...) -&gt; AsyncHttpResponse[typing.Dict[str, typing.Any]]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Revoke a permission from a principal for a resource.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import PrincipalRequest, TerminalUse, TerminalUseResource

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.authorization_internal.revoke_permission(
    operation="create",
    principal=PrincipalRequest(
        member_id="member_id",
    ),
    resource=TerminalUseResource(
        selector="selector",
        type="member",
    ),
)

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**operation:** `AuthorizedOperationType` 
    
</dd>
</dl>

<dl>
<dd>

**principal:** `PrincipalRequest` 
    
</dd>
</dl>

<dl>
<dd>

**resource:** `TerminalUseResource` 
    
</dd>
</dl>

<dl>
<dd>

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


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

<details><summary><code>client.authorization_internal.<a href="src/terminaluse/authorization_internal/client.py">revoke_all_for_resource</a>(...) -&gt; AsyncHttpResponse[RevokeAllResponse]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Revoke all permission tuples for a resource (used during deletion).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUse, TerminalUseResource

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.authorization_internal.revoke_all_for_resource(
    resource=TerminalUseResource(
        selector="selector",
        type="member",
    ),
)

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**resource:** `TerminalUseResource` 
    
</dd>
</dl>

<dl>
<dd>

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


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

<details><summary><code>client.authorization_internal.<a href="src/terminaluse/authorization_internal/client.py">search_resources</a>(...) -&gt; AsyncHttpResponse[AuthzSearchResponse]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List resource IDs that a principal can access.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import PrincipalRequest, TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.authorization_internal.search_resources(
    filter_resource="member",
    principal=PrincipalRequest(
        member_id="member_id",
    ),
)

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**filter_resource:** `TerminalUseResourceType` — Type of resource to search for
    
</dd>
</dl>

<dl>
<dd>

**principal:** `PrincipalRequest` 
    
</dd>
</dl>

<dl>
<dd>

**filter_operation:** `typing.Optional[AuthorizedOperationType]` — Operation to filter by
    
</dd>
</dl>

<dl>
<dd>

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


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

<details><summary><code>client.authorization_internal.<a href="src/terminaluse/authorization_internal/client.py">write_membership_tuple</a>(...) -&gt; AsyncHttpResponse[typing.Dict[str, typing.Any]]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Write an organization membership tuple.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.authorization_internal.write_membership_tuple(
    member_id="member_id",
    org_id="org_id",
)

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**member_id:** `str` — Member ID
    
</dd>
</dl>

<dl>
<dd>

**org_id:** `str` — Organization ID
    
</dd>
</dl>

<dl>
<dd>

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

<dl>
<dd>

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


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

<details><summary><code>client.authorization_internal.<a href="src/terminaluse/authorization_internal/client.py">delete_membership_tuple</a>(...) -&gt; AsyncHttpResponse[typing.Dict[str, typing.Any]]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Delete an organization membership tuple.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.authorization_internal.delete_membership_tuple(
    member_id="member_id",
    org_id="org_id",
)

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**member_id:** `str` — Member ID
    
</dd>
</dl>

<dl>
<dd>

**org_id:** `str` — Organization ID
    
</dd>
</dl>

<dl>
<dd>

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

<dl>
<dd>

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


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

<details><summary><code>client.authorization_internal.<a href="src/terminaluse/authorization_internal/client.py">write_parent_tuple</a>(...) -&gt; AsyncHttpResponse[typing.Dict[str, typing.Any]]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Write a parent relationship tuple to establish resource hierarchy.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.authorization_internal.write_parent_tuple(
    child_id="child_id",
    child_type="member",
    parent_id="parent_id",
    parent_type="member",
)

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**child_id:** `str` — ID of child resource
    
</dd>
</dl>

<dl>
<dd>

**child_type:** `TerminalUseResourceType` — Type of child resource
    
</dd>
</dl>

<dl>
<dd>

**parent_id:** `str` — ID of parent resource
    
</dd>
</dl>

<dl>
<dd>

**parent_type:** `TerminalUseResourceType` — Type of parent resource
    
</dd>
</dl>

<dl>
<dd>

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

<dl>
<dd>

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


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

<details><summary><code>client.authorization_internal.<a href="src/terminaluse/authorization_internal/client.py">write_role_tuple</a>(...) -&gt; AsyncHttpResponse[typing.Dict[str, typing.Any]]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Write a role tuple to grant a role on a resource.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import PrincipalRequest, TerminalUse, TerminalUseResource

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.authorization_internal.write_role_tuple(
    principal=PrincipalRequest(
        member_id="member_id",
    ),
    resource=TerminalUseResource(
        selector="selector",
        type="member",
    ),
    role="role",
)

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**principal:** `PrincipalRequest` 
    
</dd>
</dl>

<dl>
<dd>

**resource:** `TerminalUseResource` 
    
</dd>
</dl>

<dl>
<dd>

**role:** `str` — Role name (viewer, editor, admin, owner)
    
</dd>
</dl>

<dl>
<dd>

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


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

<details><summary><code>client.authorization_internal.<a href="src/terminaluse/authorization_internal/client.py">delete_role_tuple</a>(...) -&gt; AsyncHttpResponse[typing.Dict[str, typing.Any]]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Delete a role tuple to revoke a role on a resource.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import PrincipalRequest, TerminalUse, TerminalUseResource

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.authorization_internal.delete_role_tuple(
    principal=PrincipalRequest(
        member_id="member_id",
    ),
    resource=TerminalUseResource(
        selector="selector",
        type="member",
    ),
    role="role",
)

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**principal:** `PrincipalRequest` 
    
</dd>
</dl>

<dl>
<dd>

**resource:** `TerminalUseResource` 
    
</dd>
</dl>

<dl>
<dd>

**role:** `str` — Role name (viewer, editor, admin, owner)
    
</dd>
</dl>

<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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>() -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>() -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

## Versions
<details><summary><code>client.versions.<a href="src/terminaluse/versions/client.py">register</a>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

**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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

## VersionEvents
<details><summary><code>client.version_events.<a href="src/terminaluse/version_events/client.py">versions_events_list</a>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

**target_version_id:** `typing.Optional[str]` — Version ID to rollback to (defaults to previous version if not specified)
    
</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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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.Sequence[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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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.Sequence[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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 EnvVarValue, TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>(...) -&gt; AsyncHttpResponse[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 TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_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>

## Messages Batch
<details><summary><code>client.messages.batch.<a href="src/terminaluse/messages/batch/client.py">create</a>(...) -&gt; AsyncHttpResponse[typing.List[TaskMessage]]</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TaskMessageContent_ClaudeMessage, TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.messages.batch.create(
    contents=[
        TaskMessageContent_ClaudeMessage(
            author="user",
            message_type="message_type",
            raw_message={"key": "value"},
        )
    ],
    task_id="task_id",
)

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**contents:** `typing.Sequence[TaskMessageContent]` 
    
</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.messages.batch.<a href="src/terminaluse/messages/batch/client.py">update</a>(...) -&gt; AsyncHttpResponse[typing.List[TaskMessage]]</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TaskMessageContent_ClaudeMessage, TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.messages.batch.update(
    task_id="task_id",
    updates={
        "key": TaskMessageContent_ClaudeMessage(
            author="user",
            message_type="message_type",
            raw_message={"key": "value"},
        )
    },
)

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

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

<dl>
<dd>

**updates:** `typing.Dict[str, TaskMessageContent]` 
    
</dd>
</dl>

<dl>
<dd>

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


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

## Stream Events
<details><summary><code>client.stream.events.<a href="src/terminaluse/stream/events/client.py">publish</a>(...) -&gt; AsyncHttpResponse[PublishStreamEventsResponse]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Publish stream events to a task's Redis stream.

    This endpoint is used by agents to send real-time updates (deltas, full content,
    start/done signals) that clients consume via SSE endpoints like `/tasks/{task_id}/stream`.

    Events are published in order. For optimal performance with high-frequency updates
    (e.g., LLM streaming), batch multiple events in a single request.

    Requires `update` permission on the task.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from terminaluse import TaskMessageUpdate_Delta, TerminalUse

client = TerminalUse(
    agent_api_key="YOUR_AGENT_API_KEY",
    token="YOUR_TOKEN",
    base_url="https://yourhost.com/path/to/api",
)
client.stream.events.publish(
    events=[TaskMessageUpdate_Delta()],
    task_id="task_id",
)

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

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**events:** `typing.Sequence[TaskMessageUpdate]` — List of stream events to publish
    
</dd>
</dl>

<dl>
<dd>

**task_id:** `str` — Task ID to publish events to
    
</dd>
</dl>

<dl>
<dd>

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


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

