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

# 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](/cli/files)
* [`atlanai context`](/cli/reference/context)
* [`atlanai api`](/cli/reference/api)