# Onx CLI Reference

This reference documents the exact top-level commands, subcommands, arguments, and options provided by the `onx` CLI, grounded in the CLI implementation and the [Onspring API v2 Specification](https://onspringapidocs.stevanfreeborn.com/).

> [!TIP]
> **Source of Truth**: Always run `onx <command> --help` to inspect live command options and subcommands in real-time.

## Global Options

The following flags are available on the top-level command:

| Option                  | Short | Description                                                                |
| :---------------------- | :---- | :------------------------------------------------------------------------- |
| `--api-key <API_KEY>`   | `-k`  | The API key for the Onspring instance                                      |
| `--base-url <BASE_URL>` | `-u`  | The base URL for the Onspring API (defaults to `https://api.onspring.com`) |
| `--config <CONFIG>`     | `-c`  | Path to a configuration JSON file                                          |
| `--pretty`              | `-p`  | Pretty-print JSON output                                                   |
| `--help`                | `-h`  | Print help                                                                 |
| `--version`             | `-V`  | Print version                                                              |

> [!NOTE]
> Global flags (such as `--pretty`, `--api-key`, `--base-url`, `--config`) must precede the subcommand in invocation:
>
> ```bash
> onx --pretty ping
> onx --pretty records list --app 195
> ```

## `ping`

Check connectivity to the Onspring API.

```bash
onx ping
```

**Output on Success:**

```json
{
  "ok": true
}
```

## `apps`

Perform operations against the apps in the instance.

### `onx apps list`

Get a paged list of apps in the instance.

- `--page-number <PAGE_NUMBER>`, `-n`: The page number to retrieve (default: 1)
- `--page-size <PAGE_SIZE>`, `-s`: The size of the page to retrieve (default: 50, max: 1000)

**Output:**

```json
{
  "pageNumber": 1,
  "pageSize": 50,
  "totalPages": 1,
  "totalRecords": 2,
  "items": [
    {
      "href": "https://api.onspring.com/apps/id/195",
      "id": 195,
      "name": "Projects"
    }
  ]
}
```

### `onx apps get`

Get information about a specific app by ID.

- `--app <APP_ID>`, `-a`: App ID to get (required, positive integer)

### `onx apps batch-get`

Get information for a batch of apps.

- `--apps <APP_IDS>`, `-a`: Comma-separated list of app IDs to get (required, e.g. `--apps 195,196`)

## `fields`

Perform operations against the fields in the instance.

### `onx fields list`

Get a paged list of fields in an app.

- `--app <APP_ID>`, `-a`: App ID whose fields will be retrieved (required)
- `--page-number <PAGE_NUMBER>`, `-n`: Page number
- `--page-size <PAGE_SIZE>`, `-s`: Page size

### `onx fields get`

Get detailed metadata about a field (type, multiplicity, list values, formula output type).

- `--field <FIELD_ID>`, `-f`: Field ID to get (required)

### `onx fields batch-get`

Get information for a batch of fields by IDs (maximum 100).

- `--fields <FIELD_IDS>`, `-f`: Comma-separated list of field IDs to get (required, e.g. `--fields 6983,6986`)

## `records`

Perform operations against records in the instance.

### `onx records list`

Get a paged list of records from an app.

- `--app <APP_ID>`, `-a`: App ID whose records will be retrieved (required)
- `--fields <FIELD_IDS>`, `-f`: Comma-separated list of field IDs to include in the response
- `--data-format <raw|formatted>`: Format of data in the response (default: `raw`)
- `--page-number <PAGE_NUMBER>`, `-n`: Page number
- `--page-size <PAGE_SIZE>`, `-s`: Page size

### `onx records get`

Get information for a single record.

- `--app <APP_ID>`, `-a`: App ID (required)
- `--record <RECORD_ID>`, `-r`: System Record ID (required)
- `--fields <FIELD_IDS>`, `-f`: Comma-separated list of field IDs to include
- `--format <raw|formatted>`, `-d`: Format of data in response (default: `raw`)

### `onx records save`

Add or update a record.

- Input body source (choose one):
  - `--json <JSON>`, `-j`: Inline JSON request body
  - `--file <FILE>`, `-f`: Path to a JSON request body file
  - `--stdin`: Read JSON request body from stdin

**Request Format:**

```json
{
  "appId": 195,
  "recordId": null,
  "fields": {
    "6983": "New Task",
    "6986": "4118d53a-9121-4345-8682-07f23d606daa"
  }
}
```

### `onx records query`

Query for records using a filter expression.

- Input body source (choose one):
  - `--json <JSON>`, `-j`: Inline JSON request body
  - `--file <FILE>`, `-f`: Path to a JSON request body file
  - `--stdin`: Read JSON request body from stdin
- Pagination options:
  - `--page-number <PAGE_NUMBER>`, `-n`: Page number
  - `--page-size <PAGE_SIZE>`, `-s`: Page size

### `onx records delete`

Delete a single record.

- `--app <APP_ID>`, `-a`: App ID (required)
- `--record <RECORD_ID>`, `-r`: System Record ID (required)

### `onx records batch-get`

Get information for a batch of records (maximum 100).

- `--json <JSON>`, `-j` / `--file <FILE>`, `-f` / `--stdin`: JSON body `{ "appId": 195, "recordIds": [1, 2], "fieldIds": [...], "dataFormat": "Raw" }`

### `onx records batch-delete`

Delete a batch of records (maximum 100).

- `--json <JSON>`, `-j` / `--file <FILE>`, `-f` / `--stdin`: JSON body `{ "appId": 195, "recordIds": [138, 139] }`

## `files`

Perform operations against files held in `Attachment` and `Image` fields.

### `onx files info`

Get metadata info for a file.

- `--record <RECORD_ID>`, `-r`: Record ID where the file is held (required)
- `--field <FIELD_ID>`, `-f`: Field ID where the file is held (required)
- `--file <FILE_ID>`, `-l`: The ID of the file (required)

### `onx files get`

Download the content of a file.

- `--record <RECORD_ID>`, `-r`: Record ID (required)
- `--field <FIELD_ID>`, `-f`: Field ID (required)
- `--file <FILE_ID>`, `-l`: File ID (required)
- `--output <PATH>`, `-o`: Optional output path to write the downloaded file to disk (if omitted, writes binary to stdout)

### `onx files upload`

Upload a file to a field on a record.

- `--record <RECORD_ID>`, `-r`: Record ID (required)
- `--field <FIELD_ID>`, `-f`: Field ID (required)
- File source (choose one):
  - `--input <PATH>`, `-i`: Path of local file to upload
  - `--stdin`, `-s`: Read file data from stdin
- Optional metadata:
  - `--name <NAME>`, `-n`: File name (required if reading from stdin; defaults to filename if `--input` is used)
  - `--type <MIME>`, `-t`: Content MIME type (e.g. `application/pdf`; inferred if omitted)
  - `--notes <NOTES>`: Optional notes to attach to the file
  - `--modified-date <TIMESTAMP>`: Optional last modified date as RFC3339 timestamp (e.g. `2026-10-01T12:00:00Z`)

### `onx files delete`

Delete a file from an attachment/image field on a record.

- `--record <RECORD_ID>`, `-r`: Record ID (required)
- `--field <FIELD_ID>`, `-f`: Field ID (required)
- `--file <FILE_ID>`, `-l`: File ID (required)

## `lists`

Perform operations against custom lists and list values in the instance.

### `onx lists save-item`

Add or update an item for a specific list.

- `--list <LIST_ID>`, `-l`: List ID where the item should be saved (required)
- `--json <JSON>`, `-j` / `--file <FILE>`, `-f` / `--stdin`: JSON body:
  ```json
  {
    "id": null,
    "name": "In Review",
    "numericValue": 1.5,
    "color": "#ffaa00"
  }
  ```
  _(Omit `id` or pass `null` to create; provide item GUID to update)_

### `onx lists delete-item`

Delete a list item from a list.

- `--list <LIST_ID>`, `-l`: List ID (required)
- `--item <ITEM_ID>`, `-i`: GUID of the item to delete (required, e.g. `4118d53a-9121-4345-8682-07f23d606daa`)

## `reports`

Perform operations against reports in an app or survey.

### `onx reports list`

List reports available in an app or survey.

- `--app <APP_ID>`, `-a`: App ID (required)
- `--page-number <PAGE_NUMBER>`, `-n`: Page number
- `--page-size <PAGE_SIZE>`, `-s`: Page size

### `onx reports get`

Get the tabular or chart data for a specific report.

- `--report <REPORT_ID>`, `-r`: Report ID (required)
- `--format <raw|formatted>`, `-f`: Format of report data (`raw` or `formatted`, default: `raw`)
- `--type <reportData|chartData>`, `-t`: Type of report data to retrieve (`reportData` or `chartData`, default: `reportData`)
- `--page-number <PAGE_NUMBER>`, `-n`: Page number
- `--page-size <PAGE_SIZE>`, `-s`: Page size