> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the atlanai CLI; `atlanai --map json` prints its command map. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.

# atlanai file

> List, inspect, upload, download, version, and archive file artifacts.

File commands use the authenticated identity and Registry workspace scope.

## Commands

### list

Lists visible file artifacts in one workspace or across the account.

**Usage**

```text theme={null}
atlanai file list [flags]
```

| Option | Type | Default | Description |
| - | - | - | - |
| `--workspace`, `-w` | string | account-wide | Scope to one workspace. |
| `--all-workspaces`, `-A` | Boolean | `false` | Make account-wide intent explicit. |
| `--filter` | expression, repeatable | none | Filter fields with comparison operators. |
| `--fields` | string list | none | Return selected fields. |
| `--sort` | string, repeatable | server default | Sort by field; `-` means descending. |
| `--limit`, `-L` | integer | server default | Maximum results, up to `500`. |
| `--include-system` | Boolean | `false` | Include system-owned files. |
| `--json`, `--jq`, `--template` | output controls | human table | Select and format structured output. |

### get

Gets the latest or a selected version of one file artifact. `<id>` is required.

**Usage**

```text theme={null}
atlanai file get <id> [--version <ordinal>] [output flags]
```

`--version` is an integer; omit it for the latest version.

### versions

Lists every retained version for a file ID.

**Usage**

```text theme={null}
atlanai file versions <id> [output flags]
```

### upload

Uploads a local file as a new Registry file artifact.

**Usage**

```text theme={null}
atlanai file upload <path> [flags]
```

| Option | Type | Default | Description |
| - | - | - | - |
| `--workspace`, `-w` | string | active context | Workspace to upload into. Required when no context resolves. |
| `--as` | string | local filename | Stored path within the workspace. |
| `--media-type` | string | detected from extension | Content type recorded for the file. |
| `--parent-kind` | string | none | Parent artifact kind. Requires `--parent-id`. |
| `--parent-id` | string | none | Parent artifact ID. Requires `--parent-kind`. |

### download

Downloads the latest or a selected version of a file artifact.

**Usage**

```text theme={null}
atlanai file download <id> [flags]
```

| Option | Type | Default | Description |
| - | - | - | - |
| `--output`, `-o` | path | stdout | Write bytes to a file. |
| `--version` | integer | latest | Download a version ordinal. |

Binary content is refused on an interactive terminal unless `--output` or a
pipe is used. Downloads stop after 64 MiB.

### delete

Archives a file artifact while retaining its versions.

**Usage**

```text theme={null}
atlanai file delete <id> [--confirm]
```

`--confirm` skips the prompt.

Structured reads support `--json`, `--jq`, and `--template`. Valid artifact
fields are `artifact_status`, `created_at`, `description`, `id`, `is_latest`,
`is_system`, `kind`, `metadata`, `name`, `source_digest`, `updated_at`,
`version_ordinal`, and `workspace_id`.

## Examples

```bash theme={null}
atlanai file list --workspace workspace_123 --limit 20
atlanai file upload ./report.pdf --workspace workspace_123 --as reports/report.pdf
atlanai file download file_123 --version 2 --output ./report-v2.pdf
```

## Output and behavior

* Upload detects the media type from the extension when `--media-type` is
  omitted.
* Duplicate stored paths in one workspace are rejected; choose another `--as`
  value.
* A partial parent pair is rejected before upload.
* `delete` is a soft delete: listings hide the file, but versions remain.
* Empty list results exit with code `0`.

## Related

* [Work with files](/tools/cli/how-tos/files)
* [`atlanai context`](/tools/cli/references/commands/context)
* [`atlanai api`](/tools/cli/references/commands/api)