# Files Commands > See [Files module docs](../../modules/files) for permissions and data model. # Files Commands See [Files module docs](../../modules/files) for permissions and data model. ### `soat list-files` List all files - Method: `GET` - Path: `/api/v1/files` #### Usage ```bash soat list-files ``` #### Options ##### `--project-id` Filter files by project ID - Source: `query` - Required: no - Type: `string` - Example: `proj_V1StGXR8Z5jdHi6B` ##### `--limit` Maximum number of results to return - Source: `query` - Required: no - Type: `integer` - Default: `50` ##### `--offset` Number of results to skip - Source: `query` - Required: no - Type: `integer` - Default: `0` ### `soat create-file` Create a file - Method: `POST` - Path: `/api/v1/files` #### Usage ```bash soat create-file ``` #### Options ##### `--project-id` Public ID of the project. Optional when authenticating with a project-scoped API key, which defaults to the key's project; required otherwise. - Source: `body` - Required: no - Type: `string` - Example: `proj_V1StGXR8Z5jdHi6B` ##### `--prefix` Directory within the project (e.g. /images). Optional; defaults to / (root). Combined with filename to form the file's key (path). - Source: `body` - Required: no - Type: `string` - Example: `/images` ##### `--filename` Original / download name and the key's leaf segment (e.g. logo.png). - Source: `body` - Required: no - Type: `string` - Example: `logo.png` ##### `--content-type` MIME type of the file - Source: `body` - Required: no - Type: `string` - Example: `application/pdf` ##### `--size` File size in bytes - Source: `body` - Required: no - Type: `integer \| null` - Example: `1024` ##### `--metadata` JSON string with additional metadata - Source: `body` - Required: no - Type: `string` - Example: `\{"author":"John"\}` ### `soat upload-file` Upload a file - Method: `POST` - Path: `/api/v1/files/upload` #### Usage ```bash soat upload-file --file ``` #### Options ##### `--file` File content - Source: `body` - Required: yes - Type: `string` ##### `--project-id` Project ID to associate the file with. Optional when authenticating with a project-scoped API key, which defaults to the key's project; required otherwise. - Source: `body` - Required: no - Type: `string` - Example: `proj_V1StGXR8Z5jdHi6B` ##### `--prefix` Directory within the project (e.g. /images). Optional; defaults to / (root). - Source: `body` - Required: no - Type: `string` - Example: `/images` ##### `--filename` Original / download name. Optional; defaults to the uploaded file's name. - Source: `body` - Required: no - Type: `string` - Example: `logo.png` ##### `--metadata` Additional metadata as a JSON string - Source: `body` - Required: no - Type: `string` - Example: `\{"author":"John"\}` ### `soat upload-file-base64` Upload a file using base64 encoding - Method: `POST` - Path: `/api/v1/files/upload/base64` #### Usage ```bash soat upload-file-base64 --content ``` #### Options ##### `--project-id` Public ID of the project - Source: `body` - Required: no - Type: `string` - Example: `proj_V1StGXR8Z5jdHi6B` ##### `--content` Base64-encoded file content - Source: `body` - Required: yes - Type: `string` - Example: `SGVsbG8gV29ybGQ=` ##### `--prefix` Directory within the project (e.g. /documents). Optional; defaults to / (root). - Source: `body` - Required: no - Type: `string` - Example: `/documents` ##### `--filename` Original / download name and the key's leaf segment. - Source: `body` - Required: no - Type: `string` - Example: `document.txt` ##### `--content-type` MIME type of the file - Source: `body` - Required: no - Type: `string` - Example: `text/plain` ##### `--metadata` JSON string with additional metadata - Source: `body` - Required: no - Type: `string` - Example: `\{"author":"John"\}` ### `soat create-presigned-url` Create a presigned upload URL - Method: `POST` - Path: `/api/v1/files/presigned-url` #### Usage ```bash soat create-presigned-url --project-id ``` #### Options ##### `--project-id` Public ID of the project - Source: `body` - Required: yes - Type: `string` - Example: `proj_V1StGXR8Z5jdHi6B` ##### `--prefix` Directory within the project (e.g. /documents). Optional; defaults to / (root). - Source: `body` - Required: no - Type: `string` - Example: `/documents` ##### `--filename` Original / download name and the key's leaf segment. - Source: `body` - Required: no - Type: `string` - Example: `report.pdf` ##### `--content-type` MIME type of the file to be uploaded - Source: `body` - Required: no - Type: `string` - Example: `application/pdf` ### `soat upload-file-with-token` Upload a file using an upload token - Method: `POST` - Path: `/api/v1/files/upload/{token}` #### Usage ```bash soat upload-file-with-token --token ``` #### Options ##### `--token` The single-use upload token (e.g. upt_...) - Source: `path` - Required: yes - Type: `string` - Example: `upt_V1StGXR8Z5jdHi6B` ##### `--content` Base64-encoded file content (alternative to multipart `file`) - Source: `body` - Required: no - Type: `string` - Example: `SGVsbG8gV29ybGQ=` ##### `--filename` Original / download name (overrides the token's filename) - Source: `body` - Required: no - Type: `string` - Example: `document.txt` ##### `--content-type` MIME type of the file (overrides the token's content type) - Source: `body` - Required: no - Type: `string` - Example: `text/plain` ##### `--metadata` JSON string with additional metadata - Source: `body` - Required: no - Type: `string` - Example: `\{"author":"John"\}` ### `soat get-file` Get a file by ID - Method: `GET` - Path: `/api/v1/files/{file_id}` #### Usage ```bash soat get-file --file-id ``` #### Options ##### `--file-id` File ID - Source: `path` - Required: yes - Type: `string` - Example: `abc123` ### `soat delete-file` Delete a file - Method: `DELETE` - Path: `/api/v1/files/{file_id}` #### Usage ```bash soat delete-file --file-id ``` #### Options ##### `--file-id` ID of the file to delete - Source: `path` - Required: yes - Type: `string` - Example: `abc123` ### `soat download-file` Download a file - Method: `GET` - Path: `/api/v1/files/{file_id}/download` #### Usage ```bash soat download-file --file-id ``` #### Options ##### `--file-id` File ID - Source: `path` - Required: yes - Type: `string` - Example: `file_abc123` ### `soat update-file-metadata` Update file metadata - Method: `PATCH` - Path: `/api/v1/files/{file_id}/metadata` #### Usage ```bash soat update-file-metadata --file-id ``` #### Options ##### `--file-id` File ID - Source: `path` - Required: yes - Type: `string` - Example: `file_abc123` ##### `--metadata` New metadata as a JSON string - Source: `body` - Required: no - Type: `string` - Example: `\{"author":"Jane","tags":["report"]\}` ##### `--prefix` New directory — moves the file. The resulting path (prefix + filename) must be unique within the project. - Source: `body` - Required: no - Type: `string` - Example: `/reports` ##### `--filename` New filename — renames the key's leaf and the download name. - Source: `body` - Required: no - Type: `string` - Example: `renamed-file.txt` ### `soat download-file-base64` Download file as base64 - Method: `GET` - Path: `/api/v1/files/{file_id}/download/base64` #### Usage ```bash soat download-file-base64 --file-id ``` #### Options ##### `--file-id` File ID - Source: `path` - Required: yes - Type: `string` ### `soat get-file-tags` Get file tags - Method: `GET` - Path: `/api/v1/files/{file_id}/tags` #### Usage ```bash soat get-file-tags --file-id ``` #### Options ##### `--file-id` File ID - Source: `path` - Required: yes - Type: `string` ### `soat replace-file-tags` Replace file tags - Method: `PUT` - Path: `/api/v1/files/{file_id}/tags` #### Usage ```bash soat replace-file-tags --file-id ``` #### Options ##### `--file-id` File ID - Source: `path` - Required: yes - Type: `string` ### `soat merge-file-tags` Merge file tags - Method: `PATCH` - Path: `/api/v1/files/{file_id}/tags` #### Usage ```bash soat merge-file-tags --file-id ``` #### Options ##### `--file-id` File ID - Source: `path` - Required: yes - Type: `string`