datalab-cli 0.1.0

# files

File management operations.

## Synopsis

```
datalab files <COMMAND>
```

## Description

Upload, list, download, and delete files in Datalab storage. Uploaded files can be referenced in other commands using their file IDs.

---

## Commands

| Command | Description |
|---------|-------------|
| [`upload`](#upload) | Upload a file to Datalab storage |
| [`list`](#list) | List uploaded files |
| [`get`](#get) | Get file metadata |
| [`download`](#download) | Download a file |
| [`delete`](#delete) | Delete a file |

---

## upload

Upload a file to Datalab storage.

### Synopsis

```
datalab files upload [OPTIONS] <FILE>
```

### Arguments

| Argument | Description |
|----------|-------------|
| `<FILE>` | File to upload |

### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--timeout <SECS>` | Request timeout in seconds | `300` |

### Example

```bash
datalab files upload document.pdf
```

### Output

```json
{
  "file_id": "file_abc123",
  "reference": "document.pdf",
  "upload_status": "completed",
  "file_size": 1048576
}
```

---

## list

List uploaded files.

### Synopsis

```
datalab files list [OPTIONS]
```

### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--limit <N>` | Results per page (max 100) | `50` |
| `--offset <N>` | Pagination offset | `0` |
| `--timeout <SECS>` | Request timeout in seconds | `60` |

### Examples

```bash
# List first 50 files
datalab files list

# List with pagination
datalab files list --limit 100 --offset 50
```

### Output

```json
{
  "files": [
    {
      "file_id": "file_abc123",
      "filename": "document.pdf",
      "size": 1048576,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 150,
  "limit": 50,
  "offset": 0
}
```

---

## get

Get file metadata.

### Synopsis

```
datalab files get [OPTIONS] <FILE_ID>
```

### Arguments

| Argument | Description |
|----------|-------------|
| `<FILE_ID>` | File ID |

### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--timeout <SECS>` | Request timeout in seconds | `60` |

### Example

```bash
datalab files get file_abc123
```

### Output

```json
{
  "file_id": "file_abc123",
  "filename": "document.pdf",
  "size": 1048576,
  "content_type": "application/pdf",
  "created_at": "2024-01-15T10:30:00Z",
  "upload_status": "completed"
}
```

---

## download

Download a file.

### Synopsis

```
datalab files download [OPTIONS] <FILE_ID>
```

### Arguments

| Argument | Description |
|----------|-------------|
| `<FILE_ID>` | File ID |

### Options

| Option | Description | Default |
|--------|-------------|---------|
| `-o, --output <FILE>` | Output file path | - |
| `--expires-in <SECS>` | URL validity duration (max 86400) | `3600` |
| `--timeout <SECS>` | Request timeout in seconds | `300` |

### Examples

```bash
# Get download URL
datalab files download file_abc123

# Download to file
datalab files download file_abc123 --output document.pdf

# Custom URL expiration
datalab files download file_abc123 --expires-in 7200
```

### Output (without --output)

```json
{
  "download_url": "https://storage.datalab.to/...",
  "expires_at": "2024-01-15T11:30:00Z"
}
```

### Output (with --output)

```json
{
  "downloaded_to": "document.pdf",
  "size": 1048576
}
```

---

## delete

Delete a file.

### Synopsis

```
datalab files delete [OPTIONS] <FILE_ID>
```

### Arguments

| Argument | Description |
|----------|-------------|
| `<FILE_ID>` | File ID |

### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--timeout <SECS>` | Request timeout in seconds | `60` |

### Example

```bash
datalab files delete file_abc123
```

### Output

```json
{
  "deleted": true,
  "file_id": "file_abc123"
}
```

---

## Workflow Example

```bash
# 1. Upload a file
datalab files upload document.pdf
# Returns: file_id: "file_abc123"

# 2. List files
datalab files list

# 3. Get file info
datalab files get file_abc123

# 4. Download file
datalab files download file_abc123 --output downloaded.pdf

# 5. Delete when done
datalab files delete file_abc123
```

---

## Related Commands

- [`convert`](convert.md) - Convert documents (can use file IDs)
- [`extract`](extract.md) - Extract data from files

---

## See Also

- [Rate Limits](../concepts/rate-limits.md)