# `Codex.Files`
[🔗](https://github.com/nshkrdotcom/codex_sdk/blob/v0.18.1/lib/codex/files.ex#L1)

Attachment staging helpers mirroring the Python SDK file APIs.

# `attach`

```elixir
@spec attach(Codex.Thread.Options.t(), Codex.Files.Attachment.t()) ::
  Codex.Thread.Options.t()
```

Attaches an `Attachment` to the supplied `ThreadOptions`.

# `cleanup!`

```elixir
@spec cleanup!() :: :ok | {:error, term()}
```

Deprecated alias retained for backwards compatibility.

# `force_cleanup`

```elixir
@spec force_cleanup() :: :ok | {:error, term()}
```

Removes staged files that are not marked as persistent.

# `list_staged`

```elixir
@spec list_staged() :: [Codex.Files.Attachment.t()]
```

Lists staged attachments currently cached.

# `list_staged_result`

```elixir
@spec list_staged_result() :: {:ok, [Codex.Files.Attachment.t()]} | {:error, term()}
```

Lists staged attachments with explicit success/error tuples.

# `metrics`

```elixir
@spec metrics() :: map() | {:error, term()}
```

Returns high-level staging metrics including counts and total bytes.

# `reset!`

```elixir
@spec reset!() :: :ok | {:error, term()}
```

Resets the staging directory and manifest.

# `stage`

```elixir
@spec stage(
  Path.t(),
  keyword()
) :: {:ok, Codex.Files.Attachment.t()} | {:error, term()}
```

Stages a file for future attachment invocation.

Options:

  * `:name` - override the attachment name (defaults to the basename of `path`)
  * `:persist` - keep file around indefinitely (default: `false`)
  * `:ttl_ms` - custom time-to-live for ephemeral attachments. Accepts `:infinity` or a
    non-negative integer in milliseconds. Defaults to `Application.get_env/3` lookups of
    `:attachment_ttl_ms` and falls back to 24 hours.

# `staging_dir`

```elixir
@spec staging_dir() :: Path.t()
```

Returns the staging directory path.

---

*Consult [api-reference.md](api-reference.md) for complete listing*