@getfrontline/cli 1.0.0

package/dist/skills/crud-operations/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: crud-operations
+description: >
+    How to create, update, and delete fields, options, rows, record types, and views
+    using the Frontline CLI. Use when managing the schema or data of tables and objects.
+allowed-tools: Bash(frontline:*)
+---
+
+# CRUD Operations
+
+The Frontline CLI provides full CRUD for every entity on tables and objects.
+The surface is symmetric: anything you can do on a table, you can do on an object
+(objects additionally support record types, views, and relations).
+
+## Discovering the Schema
+
+Before modifying anything, always inspect the schema first:
+
+```bash
+# List all tables / objects
+frontline table list
+frontline object list
+
+# Get detailed schema (fields, relations, record types)
+frontline table schema <name>
+frontline object schema <name>
+
+# List fields (includes field IDs, types, options for select fields)
+frontline table field list <name>
+frontline object field list <name>
+```
+
+## Fields
+
+Fields are the columns of a table/object. Each field has an `id`, `name`, `type`,
+and optional metadata depending on the field type.
+
+### Field Types & Metadata Reference
+
+| Type       | Metadata keys                                                                 | Example                                                               |
+| ---------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `string`   | `format`: `text`, `email`, `url`, `phone`                                     | `{"type":"string","metadata":{"format":"email"}}`                     |
+| `number`   | `format`: `decimal`, `integer`, `percent`, `currency`; `decimals`; `currency` | `{"type":"number","metadata":{"format":"currency","currency":"USD"}}` |
+| `boolean`  | _(none)_                                                                      | `{"type":"boolean","metadata":{}}`                                    |
+| `date`     | `timezone`; `format`; `timeFormat`                                            | `{"type":"date","metadata":{"timezone":"UTC"}}`                       |
+| `dateOnly` | `format`                                                                      | `{"type":"dateOnly","metadata":{}}`                                   |
+| `select`   | `mode`: `singleSelect`, `multiSelect`                                         | `{"type":"select","metadata":{"mode":"singleSelect"}}`                |
+| `relation` | `mode`: `single`, `multi`; `relatedTableId`; `displayColumn`                  | `{"type":"relation","metadata":{"mode":"multi"}}`                     |
+| `file`     | `showPreview`; `allowedFileTypes`; `maxFileSize`                              | `{"type":"file","metadata":{"showPreview":true}}`                     |
+
+> **Note**: Field `type` in create/update is `select` (mapped internally to `tags`).
+> The API response will also return `"type": "select"`.
+
+### Create
+
+```bash
+# String field with email format
+frontline table field create <table> --data '{
+  "name": "Email",
+  "type": "string",
+  "metadata": { "format": "email" }
+}'
+
+# Number field with currency
+frontline table field create <table> --data '{
+  "name": "Amount",
+  "type": "number",
+  "metadata": { "format": "currency", "currency": "USD", "decimals": 2 }
+}'
+
+# Single-select field
+frontline object field create <object> --data '{
+  "name": "Priority",
+  "type": "select",
+  "metadata": { "mode": "singleSelect" }
+}'
+
+# Date field with timezone
+frontline table field create <table> --data '{
+  "name": "Due Date",
+  "type": "date",
+  "metadata": { "timezone": "America/New_York" }
+}'
+```
+
+### Update
+
+```bash
+# Rename a field
+frontline table field update <table> <field-id> --data '{"name": "Renamed Field"}'
+
+# Mark a field as required
+frontline object field update <object> <field-id> --data '{"required": true}'
+
+# Add a unique constraint
+frontline table field update <table> <field-id> --data '{"unique": true}'
+
+# Combine multiple changes
+frontline object field update <object> <field-id> --data '{"name": "Email", "required": true, "unique": true}'
+```
+
+Supported update keys: `name`, `metadata`, `required`, `unique`, `tags`, `defaultValue`.
+
+### Delete
+
+```bash
+frontline table field delete <table> <field-id>
+```
+
+## Options (Select Field Values)
+
+Options are the selectable values for `singleSelect` and `multiSelect` fields.
+You need the **field ID** first (use `field list`).
+
+### Available Colors
+
+Use color **names** (case-insensitive) or hex codes:
+
+`Terracotta`, `Amber`, `Lime`, `Emerald`, `Lavender`, `Sky`, `Magenta`,
+`Bright Red`, `Teal`, `Gray`, `Brown`, `Orange`, `Yellow`, `Green`,
+`Blue`, `Purple`, `Pink`, `Red`
+
+### List
+
+```bash
+frontline table option list <table> <field-id>
+frontline object option list <object> <field-id>
+```
+
+### Create
+
+```bash
+frontline object option create <object> <field-id> --data '{
+  "name": "Hot",
+  "color": "Magenta"
+}'
+```
+
+### Update / Delete
+
+```bash
+frontline object option update <object> <option-id> --data '{"name": "Warm", "color": "Amber"}'
+frontline object option delete <object> <option-id>
+```
+
+> **Note**: `option-id` is the option's own ID (not the field ID).
+
+## Rows (Records)
+
+### Create
+
+```bash
+# Body is a flat key-value map: { "Field Name": value }
+frontline table row create <table> --data '{
+  "Name": "Acme Corp",
+  "Amount": 50000,
+  "Status": [1]
+}'
+
+frontline object record create <object> --data '{
+  "First Name": "John",
+  "Last Name": "Doe",
+  "Email": "john@example.com"
+}'
+```
+
+> Select fields expect an array of option IDs: `[1, 3]`
+
+### Bulk Create
+
+You can create multiple rows or records at once by passing a JSON array to `--data`.
+
+```bash
+# Create multiple table rows
+frontline table row bulk-create <table> --data '[
+  { "Name": "Acme Corp", "Amount": 50000 },
+  { "Name": "Globex Inc", "Amount": 120000 }
+]'
+
+# Create multiple object records
+frontline object record bulk-create <object> --data '[
+  { "First Name": "John", "Last Name": "Doe" },
+  { "First Name": "Jane", "Last Name": "Smith" }
+]'
+```
+
+### Update
+
+```bash
+# Only send the fields you want to change
+frontline table row update <table> <row-id> --data '{"Amount": 75000}'
+frontline object record update <object> <row-id> --data '{"Status": [2]}'
+```
+
+### Delete
+
+```bash
+frontline table row delete <table> <row-id>
+frontline object record delete <object> <row-id>
+```
+
+### Get by ID
+
+```bash
+frontline table row get <table> <row-id>
+frontline object record get <object> <row-id>
+```
+
+## Record Types (objects only)
+
+Record types group records into categories (e.g., "Lead", "Customer" in a People object).
+
+### List
+
+```bash
+frontline object record-type list <object>
+```
+
+### Create
+
+```bash
+frontline object record-type create <object> --data '{
+  "name": "lead",
+  "displayName": "Lead",
+  "columnIds": [1, 2, 3]
+}'
+```
+
+> Passing `columnIds` auto-creates default Table + Record views with those columns.
+
+### Update / Delete
+
+```bash
+frontline object record-type update <object> <record-type-id> --data '{"displayName": "Qualified Lead"}'
+frontline object record-type delete <object> <record-type-id>
+```
+
+## Views (objects only)
+
+Views control how records are displayed in the UI (table grid, kanban board, single record).
+
+### List
+
+```bash
+frontline object view list <object>
+```
+
+### Create
+
+```bash
+# View types: table, kanban, record
+frontline object view create <record-type-id> --data '{
+  "name": "Kanban Board",
+  "type": "kanban",
+  "metadata": { "groupingColumnId": 42 }
+}'
+```
+
+### Update / Delete
+
+```bash
+frontline object view update <record-type-id> <view-id> --data '{"name": "Updated Board"}'
+frontline object view delete <record-type-id> <view-id>
+```
+
+## Workflow: Full Object Setup
+
+Create a new record type with a kanban view for a deals pipeline:
+
+```bash
+# 1. Check current fields
+frontline object field list sor__deals
+
+# 2. Create a record type (returns record_type_id)
+frontline object record-type create sor__deals --data '{
+  "name": "enterprise",
+  "displayName": "Enterprise Deals",
+  "columnIds": [1, 2, 5, 8]
+}'
+
+# 3. Add a kanban view to the record type
+frontline object view create <record-type-id> --data '{
+  "name": "Pipeline Board",
+  "type": "kanban",
+  "metadata": { "groupingColumnId": 5 }
+}'
+```

package/dist/skills/export-and-delete/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: export-and-delete
+description: >
+    How to export data and delete tables or objects using the Frontline CLI.
+    Use when you need to download records as XLSX/CSV files or permanently
+    remove a table or object and all its data.
+allowed-tools: Bash(frontline:*)
+---
+
+# Export & Delete Operations
+
+## Exporting Data
+
+Export records from a table or object as an XLSX spreadsheet or CSV file.
+Exports support the same query/search/sort filters used for listing.
+
+### Export as XLSX
+
+```bash
+frontline table export xlsx <name> [--output file.xlsx]
+frontline object export xlsx <name> [--output file.xlsx]
+```
+
+```bash
+# Export all people
+frontline object export xlsx sor__people
+
+# Export with filter (high-value deals only)
+frontline object export xlsx sor__deals \
+  --query '{"path": "[Amount]", "operator": "gte", "value": 10000}' \
+  --output big_deals.xlsx
+
+# Export with search + sort
+frontline table export xlsx sales_data \
+  --search "enterprise" \
+  --sort '[{"path": "[Revenue]", "type": "desc"}]' \
+  --output enterprise_sales.xlsx
+```
+
+### Export as CSV
+
+```bash
+frontline table export csv <name> [--output file.csv]
+frontline object export csv <name> [--output file.csv]
+```
+
+```bash
+# Export all records as CSV
+frontline object export csv sor__people --output people_backup.csv
+```
+
+### Default Output
+
+If `--output` is not specified:
+
+- XLSX: `./<name>_export.xlsx`
+- CSV: `./<name>_export.csv`
+
+## Deleting Tables/Objects
+
+> [!CAUTION]
+> These operations are **destructive and irreversible**. All rows, fields,
+> views, record types, and associated data will be permanently deleted.
+
+### Delete a Table
+
+```bash
+frontline table delete <name>
+```
+
+### Delete an Object
+
+```bash
+frontline object delete <name>
+```
+
+### Response
+
+```json
+{ "deleted": true, "name": "my_table" }
+```
+
+## Workflow: Backup Then Delete
+
+Always export before deleting:
+
+```bash
+# 1. Export everything
+frontline object export xlsx sor__legacy_deals --output legacy_deals_backup.xlsx
+
+# 2. Verify the export file exists and looks right
+ls -la legacy_deals_backup.xlsx
+
+# 3. Delete the object
+frontline object delete sor__legacy_deals
+```

package/dist/skills/files/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: files
+description: >
+    How to list, get, download, and delete files attached to rows
+    in tables and objects using the Frontline CLI.
+allowed-tools: Bash(frontline:*)
+---
+
+# File Management
+
+Files are binary attachments linked to individual rows. Each file has an
+auto-incremented ID, original filename, content type, and size.
+
+> **Note**: File _upload_ via CLI is not yet supported because it requires
+> multipart form-data. Use the web UI or direct API calls for uploads.
+
+## List Files for a Row
+
+```bash
+frontline object file list <object> <row-id>
+frontline table file list <table> <row-id>
+```
+
+Returns an array of file objects with `id`, `originalName`, `contentType`,
+`size`, and `createdAt`.
+
+## Get File Metadata
+
+```bash
+frontline object file get <object> <file-id>
+frontline table file get <table> <file-id>
+```
+
+## Download a File
+
+```bash
+# Download to current directory (uses original filename)
+frontline object file download <object> <file-id>
+
+# Download to a specific path
+frontline object file download <object> <file-id> --output ./contracts/proposal.pdf
+frontline table file download <table> <file-id> --output ./data/report.xlsx
+```
+
+## Delete a File
+
+```bash
+frontline object file delete <object> <file-id>
+frontline table file delete <table> <file-id>
+```
+
+---
+
+## Typical Workflow
+
+```bash
+# 1. Find the row
+frontline object row list sor__deals --search "Acme Corp"
+# → row ID = 6625abc123def456
+
+# 2. List attached files
+frontline object file list sor__deals 6625abc123def456
+# → [{ id: 15, originalName: "contract_v2.pdf", size: 245000, ... }]
+
+# 3. Download a file
+frontline object file download sor__deals 15 --output ./contract_v2.pdf
+
+# 4. Delete an outdated file
+frontline object file delete sor__deals 15
+```

package/dist/skills/filter-and-query/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: filter-and-query
+description: >
+    How to filter, search, and sort records using the Frontline CLI.
+    Use when you need to find specific records in a table or object by
+    building query conditions, combining them with AND/OR logic,
+    searching by text, or sorting results.
+allowed-tools: Bash(frontline:*)
+---
+
+# Filtering and Querying Records
+
+The `frontline table row list` and `frontline object record list` commands accept
+`--query`, `--search`, and `--sort` flags for filtering data.
+
+## Quick Reference
+
+```bash
+# Simple text search across all fields
+frontline object record list sor__people --search "john"
+
+# Filter by a single condition
+# TIP: Use 'frontline object field list <name>' to find field names and tag IDs
+frontline object record list sor__deals --query '{
+  "path": "[Amount]",
+  "operator": "gte",
+  "value": 10000
+}'
+
+# Multiple conditions (AND)
+frontline object record list sor__deals --query '{
+  "operator": "and",
+  "conditions": [
+    { "path": "[Status]", "operator": "containsAny", "value": [1, 2] },
+    { "path": "[Amount]", "operator": "gte", "value": 5000 }
+  ]
+}'
+
+# Sort results
+frontline object record list sor__people --sort '[{"path": "[Last Name]", "type": "asc"}]'
+```
+
+## Path Format
+
+Field paths use bracket notation: `[Field Name]`
+
+For relation fields (querying through a linked record's field):
+`[Relation Field].[Target Field]`
+
+```jsonc
+"path": "[Email]"              // Direct field
+"path": "[Company].[Name]"     // Through a relation
+```
+
+## Operators by Field Type
+
+### String Fields
+
+| Operator     | Description     | Value        |
+| ------------ | --------------- | ------------ |
+| `equals`     | Exact match     | `"string"`   |
+| `ne`         | Not equal       | `"string"`   |
+| `contains`   | Substring match | `"string"`   |
+| `startsWith` | Starts with     | `"string"`   |
+| `endsWith`   | Ends with       | `"string"`   |
+| `regex`      | Regex pattern   | `"pattern"`  |
+| `isNull`     | Field is empty  | _(no value)_ |
+| `isNotNull`  | Field has value | _(no value)_ |
+
+### Number Fields
+
+| Operator               | Description           | Value        |
+| ---------------------- | --------------------- | ------------ |
+| `equals`               | Equal to              | `number`     |
+| `ne`                   | Not equal             | `number`     |
+| `lt`                   | Less than             | `number`     |
+| `lte`                  | Less than or equal    | `number`     |
+| `gt`                   | Greater than          | `number`     |
+| `gte`                  | Greater than or equal | `number`     |
+| `in`                   | In list               | `[1, 2, 3]`  |
+| `notIn`                | Not in list           | `[1, 2, 3]`  |
+| `isNull` / `isNotNull` | Null checks           | _(no value)_ |
+
+### Date / DateOnly Fields
+
+| Operator               | Description  | Value                          |
+| ---------------------- | ------------ | ------------------------------ |
+| `equals`               | Exact date   | `"2026-04-17T00:00:00Z"`       |
+| `before`               | Before date  | `"2026-04-17T00:00:00Z"`       |
+| `after`                | After date   | `"2026-04-17T00:00:00Z"`       |
+| `onOrBefore`           | On or before | `"2026-04-17T00:00:00Z"`       |
+| `onOrAfter`            | On or after  | `"2026-04-17T00:00:00Z"`       |
+| `between`              | Date range   | `["2026-01-01", "2026-12-31"]` |
+| `isNull` / `isNotNull` | Null checks  | _(no value)_                   |
+
+### Tags (Select/Multi-select) Fields
+
+> **Important**: Tag values must be numeric **tag IDs**, not names.
+> Use `frontline table field list <table>` or `frontline object field list <object>`
+> to find tag IDs in the `options` array of each field.
+
+| Operator               | Description           | Value              |
+| ---------------------- | --------------------- | ------------------ |
+| `containsAny`          | Has any of these tags | `[1, 2]` (tag IDs) |
+| `containsAll`          | Has all of these tags | `[3, 5]` (tag IDs) |
+| `notIn`                | Does not have any of  | `[4]` (tag IDs)    |
+| `isNull` / `isNotNull` | Null checks           | _(no value)_       |
+
+### Relation Fields
+
+| Operator      | Description          | Value            |
+| ------------- | -------------------- | ---------------- |
+| `containsAny` | Linked to any of     | `["id1", "id2"]` |
+| `notIn`       | Not linked to any of | `["id1"]`        |
+| `isNull`      | No linked records    | _(no value)_     |
+| `isNotNull`   | Has linked records   | _(no value)_     |
+
+### Boolean Fields
+
+| Operator               | Description    |
+| ---------------------- | -------------- |
+| `isTrue`               | Value is true  |
+| `isFalse`              | Value is false |
+| `isNull` / `isNotNull` | Null checks    |
+
+## Combining Conditions
+
+Use `and` / `or` groups to combine conditions. Groups can be nested.
+
+```jsonc
+{
+    "operator": "or",
+    "conditions": [
+        {
+            "operator": "and",
+            "conditions": [
+                { "path": "[Status]", "operator": "containsAny", "value": [1] },
+                { "path": "[Amount]", "operator": "gte", "value": 10000 },
+            ],
+        },
+        {
+            "path": "[Priority]",
+            "operator": "containsAny",
+            "value": [5],
+        },
+    ],
+}
+```
+
+This matches: (Status is Open AND Amount >= 10000) OR Priority is Urgent.
+
+## Sorting
+
+Pass a JSON array of sort specs:
+
+```bash
+# Single sort
+frontline table row list my_table --sort '[{"path": "[Name]", "type": "asc"}]'
+
+# Multi-sort (primary + secondary)
+frontline table row list my_table --sort '[
+  {"path": "[Status]", "type": "desc"},
+  {"path": "[Created At]", "type": "asc"}
+]'
+```
+
+## Pagination
+
+```bash
+frontline table row list my_table --page 1 --page-size 50
+```
+
+- `--page`: Page number (default: 1)
+- `--page-size`: Items per page (default: 50, max: 200)
+
+## Filter by Record Type (objects only)
+
+```bash
+frontline object record list sor__people --record-type lead
+frontline object record list sor__deals --record-type "all"
+```
+
+## Full Example
+
+Find all open deals worth over $10k, owned by a specific company, sorted by amount:
+
+```bash
+frontline object record list sor__deals \
+  --query '{
+    "operator": "and",
+    "conditions": [
+      { "path": "[Status]", "operator": "containsAny", "value": [1] },
+      { "path": "[Amount]", "operator": "gte", "value": 10000 },
+      { "path": "[Company]", "operator": "isNotNull" }
+    ]
+  }' \
+  --sort '[{"path": "[Amount]", "type": "desc"}]' \
+  --page-size 20
+```