@getfrontline/cli 1.0.0

package/dist/skills/pipeline-setup/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: pipeline-setup
+description: >
+    How to set up a pipeline workflow using the Frontline CLI: create stage
+    fields, configure options, create record types, and add kanban views.
+    Use when building any staged workflow like sales pipelines, support
+    ticket flows, or project tracking boards.
+allowed-tools: Bash(frontline:*)
+---
+
+# Pipeline Setup Guide
+
+A pipeline is a visual workflow where records move through stages (e.g.,
+Lead → Qualified → Proposal → Won/Lost). This skill walks through building
+one from scratch using the Frontline CLI.
+
+## Anatomy of a Pipeline
+
+A pipeline requires three things:
+
+1. **A select field** — holds the current stage of each record
+2. **A record type** — groups fields relevant to this pipeline
+3. **A kanban view** — visualizes records as cards grouped by stage
+
+```
+┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
+│   Lead   │   │ Qualified│   │ Proposal │   │   Won    │
+│          │   │          │   │          │   │          │
+│ ┌──────┐ │   │ ┌──────┐ │   │ ┌──────┐ │   │ ┌──────┐ │
+│ │Deal A│ │   │ │Deal C│ │   │ │Deal E│ │   │ │Deal F│ │
+│ └──────┘ │   │ └──────┘ │   │ └──────┘ │   │ └──────┘ │
+│ ┌──────┐ │   │          │   │          │   │          │
+│ │Deal B│ │   │          │   │          │   │          │
+│ └──────┘ │   │          │   │          │   │          │
+└──────────┘   └──────────┘   └──────────┘   └──────────┘
+     ← Kanban view grouped by "Stage" field →
+```
+
+## Step 1 — Create the Stage Field
+
+If the object doesn't already have a stage/status field, create one:
+
+```bash
+# Check existing fields first
+frontline object field list <object>
+
+# Create a single-select field for stages
+frontline object field create <object> --data '{
+  "name": "Stage",
+  "type": "select",
+  "metadata": { "mode": "singleSelect" }
+}'
+```
+
+Note the **field ID** from the response — you'll need it for the kanban view.
+
+## Step 2 — Add Stage Options
+
+Add stages in the order they should appear on the board.
+Use colors to visually distinguish stages:
+
+```bash
+# Sales pipeline example
+frontline object option create <object> <field-id> --data '{"name": "Lead", "color": "Gray"}'
+frontline object option create <object> <field-id> --data '{"name": "Qualified", "color": "Sky"}'
+frontline object option create <object> <field-id> --data '{"name": "Proposal Sent", "color": "Amber"}'
+frontline object option create <object> <field-id> --data '{"name": "Negotiation", "color": "Lavender"}'
+frontline object option create <object> <field-id> --data '{"name": "Won", "color": "Emerald"}'
+frontline object option create <object> <field-id> --data '{"name": "Lost", "color": "Red"}'
+```
+
+### Color Suggestions by Stage Semantics
+
+| Stage type           | Suggested color  |
+| -------------------- | ---------------- |
+| New / Unqualified    | Gray             |
+| Active / In Progress | Sky, Blue        |
+| Waiting / Pending    | Amber, Yellow    |
+| Positive outcome     | Emerald, Green   |
+| Negative outcome     | Red, Bright Red  |
+| Special / VIP        | Lavender, Purple |
+
+## Step 3 — Create a Record Type
+
+Record types let you define which fields are visible for this pipeline view.
+Pick only the fields that are relevant to the workflow:
+
+```bash
+# First, find the field IDs you want to include
+frontline object field list <object>
+# Note the IDs for: Name, Stage, Value, Company, Owner, etc.
+
+# Create the record type with those field IDs
+frontline object record-type create <object> --data '{
+  "name": "sales_pipeline",
+  "displayName": "Sales Pipeline",
+  "columnIds": [1, 2, 5, 8, 12]
+}'
+```
+
+Note the **record type ID** from the response.
+
+## Step 4 — Create a Kanban View
+
+The kanban view groups records by the stage field. You can create it directly on
+the object (uses the default record type) or on a specific record type:
+
+```bash
+# Directly on the object (recommended for simple pipelines)
+frontline object view create <object> --data '{
+  "name": "Pipeline Board",
+  "type": "KANBAN",
+  "metadata": { "groupingColumnId": <stage-field-id> }
+}'
+
+# On a specific record type (optional — use when you have multiple subtypes)
+frontline object view create <object> --record-type <record-type-id> --data '{
+  "name": "Pipeline Board",
+  "type": "KANBAN",
+  "metadata": { "groupingColumnId": <stage-field-id> }
+}'
+```
+
+> `groupingColumnId` must be the ID of a single-select field.
+> View type must be uppercase: `KANBAN`, `TABLE`, `RECORD`.
+
+## Step 5 — Polish the View (Ordering and Visibility)
+
+After creating a view, you can refine which columns are visible and in what order
+without manually editing JSON. This is useful for keeping boards clean:
+
+```bash
+# Set a specific column order for the cards/table
+frontline object view update <object> <view-id> --column-order "Subject, Priority, Status"
+
+# Hide technical or system columns
+frontline object view update <object> <view-id> --hidden-columns "Created At, Updated At"
+
+# Freeze columns on the left (e.g., Name) for easier horizontal scrolling (TABLE views only)
+frontline object view update <object> <view-id> --sticky-columns "Name, Stage"
+
+# Configure the order of fields in the record creation/edit dialog
+frontline object view update <object> <view-id> --dialog-field-order "Subject, Priority, Description"
+
+# Set the order of columns (groups) in a Kanban board
+frontline object view update <object> <view-id> --option-order "New, In Progress, Closed"
+```
+
+> [!TIP]
+> **Prioritize Ergonomics**: Only show fields that help users make decisions at a
+> glance. For a Kanban board, 3-4 fields is usually the sweet spot. For tables,
+> hide system fields (`autoId`, `updatedAt`) unless they are strictly necessary.
+
+## Step 6 — Populate and Verify
+
+```bash
+# Create some records with stages
+frontline object record create <object> --data '{
+  "Name": "Acme Enterprise Deal",
+  "Stage": [1],
+  "Value": 150000
+}'
+
+frontline object record create <object> --data '{
+  "Name": "TechCorp License",
+  "Stage": [2],
+  "Value": 75000
+}'
+
+# Verify by listing records filtered by stage
+frontline object record list <object> --query '{
+  "path": "[Stage]", "operator": "containsAny", "value": [1]
+}'
+```
+
+## Complete Example: Support Ticket Pipeline
+
+```bash
+# 1. The Status field already exists on sor__tickets as a predefined field.
+#    Check its field ID and existing options:
+frontline object field list sor__tickets
+# → Status field ID = 64, existing options: New, On You, On Customer, On Hold, Closed
+
+# 2. Add more stages to the existing Status field (optionsEditable: true)
+frontline object option create sor__tickets 64 --data '{"name": "Escalated", "color": "Bright Red"}'
+frontline object option create sor__tickets 64 --data '{"name": "Waiting on Vendor", "color": "Amber"}'
+
+# 3. Also add a priority field
+frontline object field create sor__tickets --data '{
+  "name": "Priority",
+  "type": "select",
+  "metadata": { "mode": "singleSelect" }
+}'
+# → { id: 11, ... }
+
+frontline object option create sor__tickets 11 --data '{"name": "Critical", "color": "Bright Red"}'
+frontline object option create sor__tickets 11 --data '{"name": "High", "color": "Magenta"}'
+frontline object option create sor__tickets 11 --data '{"name": "Medium", "color": "Amber"}'
+frontline object option create sor__tickets 11 --data '{"name": "Low", "color": "Gray"}'
+
+# 4. Create record type with relevant fields
+frontline object field list sor__tickets
+# → Suppose: 1=Subject, 10=Status, 11=Priority, 5=Assignee, 3=Description
+
+frontline object record-type create sor__tickets --data '{
+  "name": "support_board",
+  "displayName": "Support Board",
+  "columnIds": [1, 10, 11, 5, 3]
+}'
+# → { id: 4, ... }
+
+# 5. Create kanban view grouped by Status — directly on the object
+frontline object view create sor__tickets --data '{
+  "name": "Ticket Board",
+  "type": "KANBAN",
+  "metadata": { "groupingColumnId": 10 }
+}'
+
+# 6. Create a table view too (for list browsing)
+frontline object view create sor__tickets --data '{
+  "name": "All Tickets",
+  "type": "TABLE",
+  "metadata": {}
+}'
+```
+
+## Tips
+
+- **Stage order can be customized** — use `--option-order` to control the Kanban board grouping order independently of the global select field settings.
+- **One select field per board** — each kanban view groups by exactly one select field
+- **Multiple pipelines** — create different record types for different workflows on the same object (e.g., "Sales Pipeline" and "Partner Pipeline" on Deals)
+- **Add a table view too** — kanban is great for workflow, but a table view is useful for filtering and bulk operations
+- **Use relations** — link pipeline records to people/companies for context (`frontline object relation link`)

package/dist/skills/record-type-management/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: record-type-management
+description: >
+    How to manage record types and views for custom objects using the Frontline CLI.
+    Record types allow you to group fields, and views (Table/Kanban) allow 
+    you to visualize records for a specific record type.
+allowed-tools: Bash(frontline:*)
+---
+
+# Record Type Management
+
+Custom Objects support multiple **Record Types**. Each record type can have one or more **Views** (Table or Kanban).
+
+> **Note:** These features are available for Objects created via `frontline object create`.
+> Simple tables created via `frontline table create` do not support record types or views.
+
+## Record Types
+
+A record type is a subset of fields (columns) from the object.
+
+### List Record Types
+
+```bash
+frontline object record-type list <object-name>
+```
+
+### Create a Record Type
+
+Pick the column IDs you want to include:
+
+```bash
+frontline object record-type create <object-name> --data '{
+  "name": "my_type",
+  "displayName": "My Record Type",
+  "columnIds": [1, 2, 5]
+}'
+```
+
+### Update a Record Type
+
+```bash
+frontline object record-type update <object-name> <record-type-id> --data '{
+  "displayName": "Updated Name"
+}'
+```
+
+### Delete a Record Type
+
+```bash
+frontline object record-type delete <object-name> <record-type-id>
+```
+
+---
+
+## Views
+
+Views always belong to a specific record type.
+
+### Create a Kanban View
+
+Requires a `groupingColumnId` (must be a single-select field).
+
+```bash
+frontline object view create <record-type-id> --data '{
+  "name": "Process Board",
+  "type": "kanban",
+  "metadata": { "groupingColumnId": 12 }
+}'
+```
+
+### Create a Table View
+
+```bash
+frontline object view create <record-type-id> --data '{
+  "name": "Full List",
+  "type": "table",
+  "metadata": {}
+}'
+```
+
+### List Views
+
+```bash
+frontline object view list <object-name>
+```
+
+### Update a View
+
+```bash
+# Rename the view
+frontline object view update <object-name> <view-id> --name "Renamed View"
+
+# Refine view metadata (Table/Kanban)
+frontline object view update <object-name> <view-id> --column-order "First Name, Last Name, Email"
+frontline object view update <object-name> <view-id> --hidden-columns "ID, Created At"
+frontline object view update <object-name> <view-id> --sticky-columns "First Name" # TABLE views only
+frontline object view update <object-name> <view-id> --dialog-field-order "Email, Phone"
+```
+
+### Delete a View
+
+```bash
+frontline object view delete <record-type-id> <view-id>
+```

package/dist/skills/relations/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: relations
+description: >
+    How to manage relations between object records using the Frontline CLI.
+    Use when you need to link or unlink records between objects (e.g., assign
+    a Person to a Company), query related records, or perform reverse lookups.
+allowed-tools: Bash(frontline:*)
+---
+
+# Managing Relations
+
+## Creating Relation Fields
+
+To link two objects, you must first create a **relation field** on the source object.
+
+```bash
+frontline object field create <source-obj> --data '{
+  "name": "Target Link",
+  "type": "relation",
+  "metadata": {
+    "relatedTableId": <target-table-id>,
+    "displayColumn": <target-display-column-id>,
+    "mode": "single"
+  }
+}'
+```
+
+- `relatedTableId`: The numeric ID of the target table.
+- `displayColumn`: The numeric ID of the column in the target table to show as the link title.
+- `mode`: `single` for one-to-one/many-to-one, `multi` for one-to-many.
+
+## Discovering Relations
+
+Before working with relations, inspect the object schema to find relation names:
+
+```bash
+frontline object schema sor__people
+```
+
+The output includes a `relations` array:
+
+```json
+{
+    "relations": [
+        { "name": "company", "target": "sor__companies", "mode": "multi", "display_field": "Name" },
+        { "name": "deals", "target": "sor__deals", "mode": "multi", "display_field": "Name" }
+    ]
+}
+```
+
+The `name` field is what you use as the `<relation>` argument.
+
+## Link a Record
+
+Connect a source record to a target record through a named relation:
+
+```bash
+frontline object relation link <object> <source-id> <relation> <target-id>
+```
+
+```bash
+# Link a person to a company
+frontline object relation link sor__people 6625abc123def456 Companies 6625def789abc012
+```
+
+- **Idempotent**: linking the same target twice won't create duplicates.
+- Returns the updated source record.
+
+## Unlink a Record
+
+Remove a link between two records:
+
+```bash
+frontline object relation unlink <object> <source-id> <relation> <target-id>
+```
+
+```bash
+# Remove person from company
+frontline object relation unlink sor__people 6625abc123def456 Companies 6625def789abc012
+```
+
+## Get Related Records (Forward Lookup)
+
+"What records does this person point to through `Companies`?"
+
+```bash
+frontline object relation get <object> <source-id> <relation>
+```
+
+```bash
+# Get all companies linked to this person
+frontline object relation get sor__people 6625abc123def456 Companies
+```
+
+Returns an array of related records with their full data.
+
+## Find by Relation (Reverse Lookup)
+
+"Which people point to this company?"
+
+```bash
+frontline object relation find-by <object> <relation> <target-id> [--page N] [--page-size N]
+```
+
+```bash
+# Find all people linked to a specific company
+frontline object relation find-by sor__people Companies 6625def789abc012
+
+# With pagination
+frontline object relation find-by sor__people Companies 6625def789abc012 --page 1 --page-size 20
+```
+
+Returns a paginated result: `{ rows, total_count, total_pages, current_page }`.
+
+## Workflow: Transfer a Person Between Companies
+
+```bash
+# 1. Show current company links
+frontline object relation get sor__people <person-id> Companies
+
+# 2. Unlink from old company
+frontline object relation unlink sor__people <person-id> Companies <old-company-id>
+
+# 3. Link to new company
+frontline object relation link sor__people <person-id> Companies <new-company-id>
+
+# 4. Verify
+frontline object relation get sor__people <person-id> Companies
+```
+
+## Workflow: Find All Deals for a Company
+
+```bash
+# Find deals linked to a company (reverse: deals that point to this company)
+frontline object relation find-by sor__deals Company <company-id>
+```
+
+## Filtering by Relation
+
+You can also filter records by relations using the query system
+(see `filter-and-query` skill):
+
+```bash
+# Find people with no company
+frontline object record list sor__people --query '{"path": "[Company]", "operator": "isNull"}'
+
+# Find people linked to specific companies
+frontline object record list sor__people --query '{
+  "path": "[Company]",
+  "operator": "containsAny",
+  "value": ["6625def789abc012", "6625def789abc999"]
+}'
+```

package/dist/skills/resource-creation/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: resource-creation
+description: >
+    How to create new data tables and custom objects using the Frontline CLI.
+    Use this when you need to bootstrap a new entity from scratch.
+allowed-tools: Bash(frontline:*)
+---
+
+# Resource Creation Guide
+
+This skill covers the creation of top-level entities: **Tables** and **Objects**.
+
+## Tables vs Objects: Which to Create?
+
+| Entity Type | Use Case                                                                   | Command            |
+| ----------- | -------------------------------------------------------------------------- | ------------------ |
+| **Table**   | Simple data structures, spreadsheet-like, no record types.                 | `frontline table`  |
+| **Object**  | Business entities with record types (e.g. Leads, Tickets), advanced views. | `frontline object` |
+
+## Creating a Table
+
+To create a new data table, use `frontline table create`. You MUST provide at least one column in the `--data` payload.
+
+```bash
+frontline table create <name> --data '{
+  "displayName": "Display Name",
+  "emoji": "📁",
+  "columns": [
+    { "name": "Name", "type": "string", "metadata": { "format": "text" } }
+  ]
+}'
+```
+
+### Example: Creating a "Shipments" Table
+
+```bash
+frontline table create shipments --data '{
+  "displayName": "Shipments",
+  "columns": [
+    { "name": "Cargo", "type": "string", "metadata": { "format": "text" } },
+    { "name": "Weight", "type": "number", "metadata": { "format": "decimal", "decimals": 2 } }
+  ]
+}'
+```
+
+## Creating a Custom Object
+
+To create a new custom object, use `frontline object create`. This creates a more robust entity that supports multiple record types.
+
+```bash
+frontline object create <name> --data '{
+  "displayName": "Display Name",
+  "emoji": "🎫",
+  "columns": [
+    { "name": "Subject", "type": "string", "metadata": { "format": "text" } }
+  ]
+}'
+```
+
+### Example: Creating a "Support Tickets" Object
+
+```bash
+frontline object create tickets --data '{
+  "displayName": "Support Tickets",
+  "columns": [
+    { "name": "Title", "type": "string", "metadata": { "format": "text" } },
+    { "name": "Priority", "type": "select", "metadata": { "mode": "singleSelect" } }
+  ]
+}'
+```
+
+## Naming Rules
+
+1.  **Name (slug)**: Lowercase, alphanumeric, and underscores only. E.g., `sales_leads`, `shipments_v2`.
+2.  **Display Name**: Readable text with spaces. E.g., `Sales Leads`, `Shipments V2`.
+
+## Adding More Fields
+
+Once the entity is created, you can add more fields using the `field create` subcommand:
+
+```bash
+frontline table field create <table-name> --data '{...}'
+frontline object field create <object-name> --data '{...}'
+```
+
+For a full reference on field types and metadata, see the `schema-design` skill.