# csdk CLI
## Setup
```bash
# Create a context pointing at your GraphQL endpoint
csdk context create production --endpoint https://api.example.com/graphql
# Set the active context
csdk context use production
# Authenticate
csdk auth set-token
```
## Commands
| Command | Description |
|---------|-------------|
| `context` | Manage API contexts (endpoints) |
| `auth` | Manage authentication tokens |
| `config` | Manage config key-value store (per-context) |
| `bucket` | bucket CRUD operations |
| `file` | file CRUD operations |
| `platform-bucket` | platformBucket CRUD operations |
| `platform-file` | platformFile CRUD operations |
| `files-rename` | filesRename |
| `platform-files-rename` | platformFilesRename |
| `provision-bucket` | Reconcile an S3 bucket for a logical bucket in the database.
Records the request on the bucket row via RLS; the bucket's job
trigger then enqueues the same storage:provision_bucket job used on
INSERT, and repeated requests collapse into one pending job. This is
idempotent for an already-reconciled bucket; failures become GraphQL
errors. |
| `upload-file` | Upload a file: resolves the bucket by key, creates the file row, and returns a presigned PUT URL. |
| `upload-files` | Upload multiple files: resolves the bucket by key, creates file rows, and returns presigned PUT URLs for each. Accepts at most the bucket's `maxBulkFiles` files per call. |
| `upload-platform-file` | Upload a file: resolves the bucket by key, creates the file row, and returns a presigned PUT URL. |
| `upload-platform-files` | Upload multiple files: resolves the bucket by key, creates file rows, and returns presigned PUT URLs for each. Accepts at most the bucket's `maxBulkFiles` files per call. |
## Infrastructure Commands
### `context`
Manage named API contexts (kubectl-style).
| Subcommand | Description |
|------------|-------------|
| `create --endpoint ` | Create a new context |
| `list` | List all contexts |
| `use ` | Set the active context |
| `current` | Show current context |
| `delete ` | Delete a context |
Configuration is stored at `~/.csdk/config/`.
### `auth`
Manage authentication tokens per context.
| Subcommand | Description |
|------------|-------------|
| `set-token ` | Store bearer token for current context |
| `status` | Show auth status across all contexts |
| `logout` | Remove credentials for current context |
### `config`
Manage per-context key-value configuration variables.
| Subcommand | Description |
|------------|-------------|
| `get ` | Get a config value |
| `set ` | Set a config value |
| `list` | List all config values |
| `delete ` | Delete a config value |
Variables are scoped to the active context and stored at `~/.csdk/config/`.
## Table Commands
### `bucket`
CRUD operations for Bucket records.
| Subcommand | Description |
|------------|-------------|
| `list` | List all bucket records |
| `find-first` | Find first matching bucket record |
| `get` | Get a bucket by id |
| `create` | Create a new bucket |
| `update` | Update an existing bucket |
| `delete` | Delete a bucket |
**Fields:**
| Field | Type |
|-------|------|
| `actorId` | UUID |
| `allowCustomKeys` | Boolean |
| `allowedMimeTypes` | String |
| `allowedOrigins` | String |
| `createdAt` | Datetime |
| `databaseId` | UUID |
| `description` | String |
| `destinationBucketId` | UUID |
| `id` | UUID |
| `isPublic` | Boolean |
| `key` | String |
| `maxBulkFiles` | Int |
| `maxFileSize` | BigInt |
| `physicalName` | String |
| `provisionRequestedAt` | Datetime |
| `stagingTtl` | Interval |
| `tags` | String |
| `type` | BucketType |
| `updatedAt` | Datetime |
**Required create fields:** `actorId`, `databaseId`, `key`
**Optional create fields (backend defaults):** `allowCustomKeys`, `allowedMimeTypes`, `allowedOrigins`, `description`, `destinationBucketId`, `isPublic`, `maxFileSize`, `physicalName`, `provisionRequestedAt`, `stagingTtl`, `tags`, `type`
### `file`
CRUD operations for File records.
| Subcommand | Description |
|------------|-------------|
| `list` | List all file records |
| `find-first` | Find first matching file record |
| `get` | Get a file by id |
| `update` | Update an existing file |
| `delete` | Delete a file |
**Fields:**
| Field | Type |
|-------|------|
| `actorId` | UUID |
| `bucketId` | UUID |
| `contentHash` | String |
| `createdAt` | Datetime |
| `databaseId` | UUID |
| `description` | String |
| `downloadUrl` | String |
| `expiryEnqueuedAt` | Datetime |
| `filePath` | String |
| `filename` | String |
| `id` | UUID |
| `isPublic` | Boolean |
| `key` | String |
| `mimeType` | String |
| `promotedAt` | Datetime |
| `rejectionReason` | String |
| `size` | BigInt |
| `status` | FileStatus |
| `tags` | String |
| `updatedAt` | Datetime |
| `upload` | Upload |
| `uploadUrl` | String |
| `uploadVersions` | FileVersion |
**Required create fields:** `actorId`, `bucketId`, `contentHash`, `databaseId`, `description`, `expiryEnqueuedAt`, `filename`, `isPublic`, `key`, `mimeType`, `promotedAt`, `rejectionReason`, `size`, `status`, `tags`, `upload`
### `platform-bucket`
CRUD operations for PlatformBucket records.
| Subcommand | Description |
|------------|-------------|
| `list` | List all platformBucket records |
| `find-first` | Find first matching platformBucket record |
| `get` | Get a platformBucket by id |
| `create` | Create a new platformBucket |
| `update` | Update an existing platformBucket |
| `delete` | Delete a platformBucket |
**Fields:**
| Field | Type |
|-------|------|
| `actorId` | UUID |
| `allowCustomKeys` | Boolean |
| `allowedMimeTypes` | String |
| `allowedOrigins` | String |
| `createdAt` | Datetime |
| `description` | String |
| `destinationBucketId` | UUID |
| `id` | UUID |
| `isPublic` | Boolean |
| `key` | String |
| `maxBulkFiles` | Int |
| `maxFileSize` | BigInt |
| `physicalName` | String |
| `provisionRequestedAt` | Datetime |
| `stagingTtl` | Interval |
| `tags` | String |
| `type` | BucketType |
| `updatedAt` | Datetime |
**Required create fields:** `actorId`, `key`
**Optional create fields (backend defaults):** `allowCustomKeys`, `allowedMimeTypes`, `allowedOrigins`, `description`, `destinationBucketId`, `isPublic`, `maxFileSize`, `physicalName`, `provisionRequestedAt`, `stagingTtl`, `tags`, `type`
### `platform-file`
CRUD operations for PlatformFile records.
| Subcommand | Description |
|------------|-------------|
| `list` | List all platformFile records |
| `find-first` | Find first matching platformFile record |
| `get` | Get a platformFile by id |
| `update` | Update an existing platformFile |
| `delete` | Delete a platformFile |
**Fields:**
| Field | Type |
|-------|------|
| `actorId` | UUID |
| `bucketId` | UUID |
| `contentHash` | String |
| `createdAt` | Datetime |
| `description` | String |
| `downloadUrl` | String |
| `expiryEnqueuedAt` | Datetime |
| `filePath` | String |
| `filename` | String |
| `id` | UUID |
| `isPublic` | Boolean |
| `key` | String |
| `mimeType` | String |
| `promotedAt` | Datetime |
| `rejectionReason` | String |
| `size` | BigInt |
| `status` | FileStatus |
| `tags` | String |
| `updatedAt` | Datetime |
| `upload` | Upload |
| `uploadUrl` | String |
| `uploadVersions` | FileVersion |
**Required create fields:** `actorId`, `bucketId`, `contentHash`, `description`, `expiryEnqueuedAt`, `filename`, `isPublic`, `key`, `mimeType`, `promotedAt`, `rejectionReason`, `size`, `status`, `tags`, `upload`
## Custom Operations
### `files-rename`
filesRename
- **Type:** mutation
- **Arguments:**
| Argument | Type |
|----------|------|
| `--input.clientMutationId` | String |
| `--input.fileId` | UUID |
| `--input.newFilename` | String |
### `platform-files-rename`
platformFilesRename
- **Type:** mutation
- **Arguments:**
| Argument | Type |
|----------|------|
| `--input.clientMutationId` | String |
| `--input.fileId` | UUID |
| `--input.newFilename` | String |
### `provision-bucket`
Reconcile an S3 bucket for a logical bucket in the database.
Records the request on the bucket row via RLS; the bucket's job
trigger then enqueues the same storage:provision_bucket job used on
INSERT, and repeated requests collapse into one pending job. This is
idempotent for an already-reconciled bucket; failures become GraphQL
errors.
- **Type:** mutation
- **Arguments:**
| Argument | Type |
|----------|------|
| `--input.bucketKey` | String (required) |
| `--input.ownerId` | UUID |
### `upload-file`
Upload a file: resolves the bucket by key, creates the file row, and returns a presigned PUT URL.
- **Type:** mutation
- **Arguments:**
| Argument | Type |
|----------|------|
| `--input.bucketKey` | String |
| `--input.contentHash` | String (required) |
| `--input.contentType` | String (required) |
| `--input.databaseId` | UUID |
| `--input.filename` | String |
| `--input.isPublic` | Boolean |
| `--input.key` | String |
| `--input.size` | Int (required) |
### `upload-files`
Upload multiple files: resolves the bucket by key, creates file rows, and returns presigned PUT URLs for each. Accepts at most the bucket's `maxBulkFiles` files per call.
- **Type:** mutation
- **Arguments:**
| Argument | Type |
|----------|------|
| `--input.bucketKey` | String |
| `--input.databaseId` | UUID |
| `--input.files` | UploadFileBulkFileInput (required) |
| `--input.isPublic` | Boolean |
### `upload-platform-file`
Upload a file: resolves the bucket by key, creates the file row, and returns a presigned PUT URL.
- **Type:** mutation
- **Arguments:**
| Argument | Type |
|----------|------|
| `--input.bucketKey` | String |
| `--input.contentHash` | String (required) |
| `--input.contentType` | String (required) |
| `--input.filename` | String |
| `--input.isPublic` | Boolean |
| `--input.key` | String |
| `--input.size` | Int (required) |
### `upload-platform-files`
Upload multiple files: resolves the bucket by key, creates file rows, and returns presigned PUT URLs for each. Accepts at most the bucket's `maxBulkFiles` files per call.
- **Type:** mutation
- **Arguments:**
| Argument | Type |
|----------|------|
| `--input.bucketKey` | String |
| `--input.files` | UploadPlatformFileBulkFileInput (required) |
| `--input.isPublic` | Boolean |
## Output
All commands output JSON to stdout. Pipe to `jq` for formatting:
```bash
csdk car list | jq '.[]'
csdk car get --id | jq '.'
```
## Non-Interactive Mode
Use `--no-tty` to skip all interactive prompts (useful for scripts and CI):
```bash
csdk --no-tty car create --name "Sedan" --year 2024
```