--- title: files description: Manage Workspace file metadata and content. canonical_url: https://orchestor.io/docs/en/cli/files markdown_url: https://orchestor.io/docs/en/cli/files.md contentType: reference --- # files `orc files` filters Workspace files by purpose or owner, registers and retrieves metadata, and uploads file content. Manage Issue attachments, brand assets, knowledge-base documents, and other files by ID. Authentication and a selected Workspace are required. `create`, which registers file metadata, is separate from `content update`, which sends the binary content. Use `--file`, not JSON `--stdin`, for binary uploads. ## Usage ```bash title="terminal" orc files list --purpose knowledge-base --json ``` *List knowledge-base documents in the Workspace.* ## Subcommands ### `list` Lists files filtered by purpose or owner. For Issue attachments, combine `--owner-type issue` with `--owner-id`. `--order` is `asc` or `desc` by creation time and ID; paginate with `--limit` and `--cursor`. ```bash title="terminal" orc files list [options] ``` #### Unique options ##### `--purpose` Include only files with this purpose. Omit for all purposes in the workspace.; enum: agent-context|brand-asset|chat-attachment|document|screenshot|export|profile-image|docs-asset|domain-favicon Type: `string`. Optional. ```bash title="terminal" orc files list --purpose ``` ##### `--owner-type` Owner type for an ownership filter. Must be paired with one or more repeated `owner_id` values. Issue attachments use `issue`.; enum: issue Type: `string`. Optional. ```bash title="terminal" orc files list --owner-type ``` ##### `--owner-id` Owner ID values for an ownership filter. Repeat this parameter to return files owned by any of several issues in one read.; csv Type: `string`. Optional. ```bash title="terminal" orc files list --owner-id ``` ##### `--order` Sort order by created_at, then id.; enum: asc|desc Type: `string`. Optional. ```bash title="terminal" orc files list --order ``` ### `create` Creates a file registration with `purpose`, `filename`, `mime_type`, and `byte_size`. You can also supply `sha256`, JSON `metadata`, and a structured `owner_ref`. Issue attachment ownership uses type `issue` and the Issue ID. ```bash title="terminal" orc files create [options] ``` #### Unique options ##### `--idempotency-key` Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation. Type: `string`. Optional. ```bash title="terminal" orc files create --idempotency-key ``` ##### `--purpose` (required) File usage category. Determines applicable upload policy. Use document for a general document or chat-attachment for an attachment.; enum: agent-context|brand-asset|chat-attachment|document|screenshot|export|profile-image|docs-asset|domain-favicon Type: `string`. Optional. ```bash title="terminal" orc files create --purpose ``` ##### `--filename` (required) Display filename. Leading and trailing whitespace is removed; the result must not be empty. Type: `string`. Optional. ```bash title="terminal" orc files create --filename ``` ##### `--mime-type` (required) MIME type of the binary content, such as text/plain. Accepted types depend on purpose. Type: `string`. Optional. ```bash title="terminal" orc files create --mime-type ``` ##### `--byte-size` (required) Expected binary content size in bytes. Must be a non-negative integer; purpose-specific size limits also apply. Type: `number`. Optional. ```bash title="terminal" orc files create --byte-size ``` ##### `--sha256` Optional 64-character hexadecimal hash for workspace-scoped deduplication. Normalized to lowercase. Omit to register a new storage key. Type: `string`. Optional. ```bash title="terminal" orc files create --sha256 ``` ##### `--metadata` Optional caller-defined metadata object. Defaults to {}.; (JSON object, e.g. '{"custom_id":"x"}') Type: `string`. Optional. ```bash title="terminal" orc files create --metadata ``` ##### `--owner-ref` Optional ownership reference. Issue attachments must use `{ "type": "issue", "id": "" }`. Type: `string`. Optional. ```bash title="terminal" orc files create --owner-ref ``` ### `get` Retrieves metadata by file ID. This is separate from retrieving binary content. ```bash title="terminal" orc files get [options] ``` ### `content get` Calls the content retrieval API for a file ID. The current CLI response handling passes through text, so do not use it to preserve original binary files such as images. ```bash title="terminal" orc files content get [options] ``` ### `content update` Uploads binary content using a file ID and a local path in `--file`. `--file` is required, and combining it with `--stdin` is rejected. ```bash title="terminal" orc files content update [options] ``` #### Unique options ##### `--file` Path to the local file to upload as binary content Type: `string`. Required. ```bash title="terminal" orc files content update --file ``` ## Examples ### Inspect metadata for a file ID. ```bash title="terminal" orc files get FILE_ID --json ``` *Inspect metadata for a file ID.* ### Upload local content to a registered file. ```bash title="terminal" orc files content update FILE_ID --file ./document.pdf --json ``` *Upload local content to a registered file.* ## Global Options The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc files`: - [`--help`](https://orchestor.io/docs/cli/global-flags.md#help) - [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace) - [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format) - [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output) - [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output) - [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager) - [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run) - [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation) - [`--limit`](https://orchestor.io/docs/cli/global-flags.md) - [`--cursor`](https://orchestor.io/docs/cli/global-flags.md) - [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages) - [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing) - [`--readonly`](https://orchestor.io/docs/cli/global-flags.md#read-only-mode) - [`--wrap-untrusted`](https://orchestor.io/docs/cli/global-flags.md#untrusted-content-wrapping) For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md). --- [Documentation index](https://orchestor.io/docs/llms.txt)