---
title: files
description: Workspaceのファイル情報と内容を管理する。
canonical_url: https://orchestor.io/docs/cli/files
markdown_url: https://orchestor.io/docs/cli/files.md
contentType: reference
---

# files

`orc files` は、Workspaceに保存したファイルの用途や所有者で一覧を絞り込み、メタデータを登録・取得し、ファイル内容をアップロードするコマンドです。Issueの添付やブランド資料、ナレッジベースなどのファイルをIDで管理します。

実行には認証とWorkspaceの選択が必要です。ファイルの登録情報を作る `create` と、実際のバイナリを送る `content update` は別の操作です。バイナリのアップロードにはJSONの `--stdin` ではなく `--file` を使用します。

## 使い方

```bash title="terminal"
orc files list --purpose knowledge-base --json
```

*Workspaceのナレッジベース資料を一覧にします。*

## サブコマンド

### `list`

用途や所有者で絞り込んで一覧にします。Issueの添付を取得する場合は `--owner-type issue` と `--owner-id` を組み合わせます。`--order` は作成日時とIDの `asc` または `desc` で、`--limit` と `--cursor` でページを指定します。

```bash title="terminal"
orc files list [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

型: `string`。任意。

```bash title="terminal"
orc files list --purpose <value>
```

##### `--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

型: `string`。任意。

```bash title="terminal"
orc files list --owner-type <value>
```

##### `--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

型: `string`。任意。

```bash title="terminal"
orc files list --owner-id <value>
```

##### `--order`

Sort order by created_at, then id.; enum: asc|desc

型: `string`。任意。

```bash title="terminal"
orc files list --order <value>
```

### `create`

`purpose`、`filename`、`mime_type`、`byte_size` を指定してファイルの登録情報を作成します。`sha256`、JSONの `metadata`、構造化した `owner_ref` も指定できます。Issue添付の `owner_ref` は種類 `issue` とIssue IDを使用します。

```bash title="terminal"
orc files create [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.

型: `string`。任意。

```bash title="terminal"
orc files create --idempotency-key <value>
```

##### `--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

型: `string`。任意。

```bash title="terminal"
orc files create --purpose <value>
```

##### `--filename`

(required) Display filename. Leading and trailing whitespace is removed; the result must not be empty.

型: `string`。任意。

```bash title="terminal"
orc files create --filename <value>
```

##### `--mime-type`

(required) MIME type of the binary content, such as text/plain. Accepted types depend on purpose.

型: `string`。任意。

```bash title="terminal"
orc files create --mime-type <value>
```

##### `--byte-size`

(required) Expected binary content size in bytes. Must be a non-negative integer; purpose-specific size limits also apply.

型: `number`。任意。

```bash title="terminal"
orc files create --byte-size <value>
```

##### `--sha256`

Optional 64-character hexadecimal hash for workspace-scoped deduplication. Normalized to lowercase. Omit to register a new storage key.

型: `string`。任意。

```bash title="terminal"
orc files create --sha256 <value>
```

##### `--metadata`

Optional caller-defined metadata object. Defaults to {}.; (JSON object, e.g. '{"custom_id":"x"}')

型: `string`。任意。

```bash title="terminal"
orc files create --metadata <value>
```

##### `--owner-ref`

Optional ownership reference. Issue attachments must use
`{ "type": "issue", "id": "<issue id>" }`.

型: `string`。任意。

```bash title="terminal"
orc files create --owner-ref <value>
```

### `get`

ファイルIDを指定してメタデータを取得します。バイナリ内容の取得とは別の操作です。

```bash title="terminal"
orc files get <file-id> [options]
```

### `content get`

ファイルIDを指定して内容取得APIを呼び出します。現在のCLIの応答処理はテキストを経由するため、画像などのバイナリを原本どおり保存する用途には使用しないでください。

```bash title="terminal"
orc files content get <file-id> [options]
```

### `content update`

ファイルIDと `--file` にローカルファイルのパスを指定してバイナリ内容を送信します。`--file` が必須で、`--stdin` との併用は拒否されます。

```bash title="terminal"
orc files content update <file-id> [options]
```

#### 固有のオプション

##### `--file`

Path to the local file to upload as binary content

型: `string`。必須。

```bash title="terminal"
orc files content update <file-id> --file <value>
```

## 使用例

### ファイルIDのメタデータを確認します。

```bash title="terminal"
orc files get FILE_ID --json
```

*ファイルIDのメタデータを確認します。*

### 登録済みファイルへローカルの内容をアップロードします。

```bash title="terminal"
orc files content update FILE_ID --file ./document.pdf --json
```

*登録済みファイルへローカルの内容をアップロードします。*

## グローバルオプション

`orc files` では、次の[グローバルオプション](https://orchestor.io/docs/cli/global-flags.md)を使用できます。

- [`--help`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%98%E3%83%AB%E3%83%97)
- [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AF%E3%83%BC%E3%82%AF%E3%82%B9%E3%83%9A%E3%83%BC%E3%82%B9)
- [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-%E5%87%BA%E5%8A%9B)
- [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-%E5%87%BA%E5%8A%9B)
- [`--format`](https://orchestor.io/docs/cli/global-flags.md#%E5%87%BA%E5%8A%9B%E5%BD%A2%E5%BC%8F)
- [`--field`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89%E3%81%AE%E6%8A%BD%E5%87%BA)
- [`--fields`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89%E3%81%AE%E6%8A%BD%E5%87%BA)
- [`--raw`](https://orchestor.io/docs/cli/global-flags.md#%E5%80%A4%E3%81%A0%E3%81%91%E3%82%92%E5%87%BA%E5%8A%9B)
- [`--output`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%B8%E3%81%AE%E5%87%BA%E5%8A%9B)
- [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%9A%E3%83%BC%E3%82%B8%E9%80%81%E3%82%8A)
- [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E3%81%AE%E4%BA%8B%E5%89%8D%E7%A2%BA%E8%AA%8D)
- [`--yes`](https://orchestor.io/docs/cli/global-flags.md#%E7%A2%BA%E8%AA%8D%E3%81%AE%E7%9C%81%E7%95%A5)
- [`--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#%E6%A8%99%E6%BA%96%E5%85%A5%E5%8A%9B)
- [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#%E6%A8%99%E6%BA%96%E5%85%A5%E5%8A%9B)
- [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#%E3%81%99%E3%81%B9%E3%81%A6%E3%81%AE%E3%83%9A%E3%83%BC%E3%82%B8%E3%82%92%E5%8F%96%E5%BE%97)
- [`--timing`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E6%99%82%E9%96%93)
- [`--readonly`](https://orchestor.io/docs/cli/global-flags.md#%E8%AA%AD%E3%81%BF%E5%8F%96%E3%82%8A%E5%B0%82%E7%94%A8%E3%83%A2%E3%83%BC%E3%83%89)
- [`--wrap-untrusted`](https://orchestor.io/docs/cli/global-flags.md#%E5%A4%96%E9%83%A8%E3%83%86%E3%82%AD%E3%82%B9%E3%83%88%E3%81%AE%E7%9B%AE%E5%8D%B0%E4%BB%98%E3%81%91)

各オプションの詳細と使用例は、[グローバルオプション](https://orchestor.io/docs/cli/global-flags.md)を参照してください。

---

[Documentation index](https://orchestor.io/docs/llms.txt)