Stevan/onx-skill
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore: initial commit

Browse Source
This commit is contained in:
Stevan Freeborn committed 2026-10-01 14:43:01 -05:00
commit 433471fd24
12 files changed
+1073
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

references/cli-reference.md
+277
View File
@@ -0,0 +1,277 @@
# 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
references/configuration.md
+69
View File
@@ -0,0 +1,69 @@
# Configuration Reference for `onx`
`onx` can be configured using command-line arguments, a JSON configuration file, or environment variables.
## Precedence
Settings are resolved in the following priority order (highest to lowest):
1. **Command-line flags** (`--api-key`, `--base-url`, `--pretty`, `--config`)
2. **Configuration file** (`~/.config/onx/config.json` or path specified by `--config`)
3. **Environment variables** (`ONSPRING_API_KEY`, `ONSPRING_BASE_URL`)
## Environment Variables
Recommended for automated agent sessions, CI/CD, and containers:
| Variable | Description | Example |
| :------------------ | :-------------------------------------------------------------------------- | :------------------------- |
| `ONSPRING_API_KEY` | Your Onspring API Key | `abcd-1234-efgh-5678` |
| `ONSPRING_BASE_URL` | Base URL of your Onspring instance (defaults to `https://api.onspring.com`) | `https://api.onspring.com` |
### Setting in Unix (Bash / Zsh)
```bash
export ONSPRING_API_KEY="your-api-key"
export ONSPRING_BASE_URL="https://api.onspring.com"
```
### Setting in Windows (PowerShell)
```powershell
$env:ONSPRING_API_KEY = "your-api-key"
$env:ONSPRING_BASE_URL = "https://api.onspring.com"
```
---
## Configuration File
By default, `onx` checks for a configuration file at:
- **Unix / macOS**: `~/.config/onx/config.json`
- **Windows**: `%USERPROFILE%\.config\onx\config.json`
### Format
```json
{
"apiKey": "your-api-key",
"baseUrl": "https://api.onspring.com",
"pretty": true
}
```
### Custom Config Location
You can supply a custom config file path to any command with `--config`:
```bash
onx apps list --config ./my-onspring-config.json
```
## Command-Line Options
Every command supports passing credentials directly:
```bash
onx ping --api-key "your-api-key" --base-url "https://api.onspring.com" --pretty
```
references/record-payloads.md
+186
View File
@@ -0,0 +1,186 @@
# Onspring Record Payloads & API Data Types Reference
This reference describes the exact JSON structures, data formats, and filter syntax used with `onx records save`, `onx records query`, `onx records batch-get`, and `onx records batch-delete`, grounded in the [Onspring API v2 Specification](https://onspringapidocs.stevanfreeborn.com/).
## `records save` Payload
Used for creating or updating records:
```bash
onx records save --json '<JSON_STRING>'
# or
onx records save --file ./record.json
# or
cat ./record.json | onx records save --stdin
```
### JSON Structure
```json
{
"appId": 195,
"recordId": null,
"fields": {
"6983": "A New Test Task",
"6984": "<p>This is a test task.</p>",
"6985": "2026-10-01T06:00:00Z",
"6986": "4118d53a-9121-4345-8682-07f23d606daa",
"6987": [4],
"6988": 100.5
}
}
```
### Input Fields Specification
| Property | Type | Description |
| :--------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
| `appId` | `number` | The ID of the app that contains or will contain the record (required). |
| `recordId` | `number \| null` | The ID of the record to update. If `null` or omitted, a new record is created. |
| `fields` | `object` | Key-value mapping where each key is the string representation of a **Field ID**, and the value is formatted per the field's data type. |
### Field Value Types When Saving
- **Text / Multi-line Text**: `string` (e.g., `"Title"` or HTML `"<p>Description</p>"`).
- **Number / Currency**: `number` (e.g., `42`, `100.50`).
- **Date / Time**: `string` in UTC ISO 8601 format (e.g., `"2026-10-01T12:00:00Z"`). Dates are always passed back and forth in UTC.
- **List (Single-Select)**: `string` containing the GUID of the chosen list value (e.g., `"4118d53a-9121-4345-8682-07f23d606daa"`).
- **List (Multi-Select)**: Array of GUID strings `string[]` (e.g., `["4118d53a-...", "1c1c5f7e-..."]`).
- **Reference (Single-Select)**: Array with one integer record ID `[140]` or integer `140`.
- **Reference (Multi-Select)**: Array of integer record IDs (e.g., `[140, 141]`).
- **Attachment / File**: Uploaded separately via `onx files upload`.
### Output on Success (`onx records save`)
```json
{
"id": 140,
"warnings": []
}
```
## `records query` Payload & Filter Syntax
Used for filtering and querying records across an app:
```bash
onx records query --json '<JSON_STRING>'
```
### JSON Structure
```json
{
"appId": 195,
"filter": "6983 eq 'Test Task' and 6987 gt 50",
"fieldIds": [6983, 6986, 6987],
"dataFormat": "Formatted"
}
```
### Request Fields
| Property | Type | Description |
| :----------- | :--------- | :------------------------------------------------------------------------------------------- |
| `appId` | `number` | App ID containing the records (required). |
| `filter` | `string` | Filter expression referencing Field IDs (required). |
| `fieldIds` | `number[]` | Optional array of field IDs to include in the response. If omitted, all fields are returned. |
| `dataFormat` | `string` | Optional: `"Raw"` or `"Formatted"` (defaults to `"Raw"`). |
### Query Filter Operators & Rules
Filter expressions evaluate field values using Field IDs as identifiers.
| Operator | Description | Applicable Field Types |
| :--------- | :----------------------------------- | :----------------------------------------------------------- |
| `eq` | Equals | Text, Number, Date, Auto-Number, Formulas (text/number/date) |
| `ne` | Not equals | Text, Number, Date, Auto-Number, Formulas (text/number/date) |
| `lt` | Less than | Number, Date, Auto-Number, Formulas (number/date) |
| `gt` | Greater than | Number, Date, Auto-Number, Formulas (number/date) |
| `contains` | List contains item (by name or GUID) | List fields, List formulas |
| `isnull` | Field has no value | Text, Number, Date, Auto-Number, Formulas |
| `notnull` | Field has a value | Text, Number, Date, Auto-Number, Formulas |
#### Literal Delimiters
- **String values**: Must be enclosed in single quotes `'` (e.g., `6983 eq 'Active'`).
- **Date values**: Must be enclosed in single quotes `'` preceded by `datetime` (e.g., `6985 gt datetime'2026-01-01T00:00:00Z'`).
- **Logical combination**: Combine with `and`, `or`, and negate with `not`. Group expressions using parentheses `( ... )`.
Example:
```text
(6983 eq 'Active' or 6983 eq 'Pending') and 6987 gt 100 and 6985 notnull
```
## `records batch-get` Payload
Used to fetch specific records in bulk (maximum 100 records per request):
```bash
onx records batch-get --json '{
"appId": 195,
"recordIds": [1, 2, 3],
"fieldIds": [6983, 6986],
"dataFormat": "Formatted"
}'
```
Output:
```json
{
"count": 3,
"items": [
{
"appId": 195,
"recordId": 1,
"fieldData": [
{
"type": "String",
"fieldId": 6983,
"value": "Task 1"
}
]
}
]
}
```
## `records batch-delete` Payload
Used to delete records in bulk (maximum 100 records per request):
```bash
onx records batch-delete --json '{
"appId": 195,
"recordIds": [138, 139]
}'
```
Output on success:
```json
{
"ok": true
}
```
## Understanding `dataFormat`: `Raw` vs `Formatted`
When retrieving records (`list`, `get`, `batch-get`, `query`) or reports, `dataFormat` controls the output format:
| Field Type | `Raw` Format | `Formatted` Format |
| :-------------------- | :------------------------------------------------------------------------ | :--------------------------------------------------------------- |
| **AutoNumber** | `number` (e.g. `1`) | Formatted `string` (e.g. `"APP-001"`) |
| **Date/Time** | ISO 8601 UTC string (e.g. `"2026-10-01T06:00:00Z"`) | Display string with user formatting (e.g. `"10/1/2026 6:00 AM"`) |
| **List** | Value GUID string(s) | Value name string(s) (e.g. `"In Progress"`) |
| **Number / Currency** | `number` (e.g. `100.5`) | Display string with symbol (e.g. `"$100.50"`) |
| **Text** | HTML string (e.g. `"<p>Sample</p>"`) | Plain string with HTML stripped (e.g. `"Sample"`) |
| **TimeSpan** | Object `{ "quantity": 10, "increment": "Minutes", "recurrence": "None" }` | Display string (e.g. `"10 Minutes"`) |
## Record ID vs Display Field
> [!IMPORTANT]
> The `recordId` used in `onx` CLI commands (`--record <ID>`) and API routes is the integer **system record ID** (e.g., `140`).
> Do not confuse this with the text value formatted by an **AutoNumber** or Display field in the Onspring GUI (e.g., `"INC-1002"`).