Guide

Define a board

Go from nothing to a typed, agent-ready board in three steps: create it, give it a schema, and verify the shape. Under two minutes, no config screens.

1 · Create the board

Create a board from a name. Capture the returned id — it is the opaque ref you pass to every later call:

tix board create

tix board create --name "Chat feedback" \
  --description "Triage inbound customer feedback" --format json
# → { "id": "...", "slug": "chat-feedback", "url": "https://artifacts.md/..." }

2 · Give it a schema

Keep the shape in your repo as a board.yaml so it is reviewable and version-controlled. Each field is typed — see Typed fields & schema for the full list of ten types:

board.yaml

schemaVersion: 1
fields:
  - key: severity
    name: Severity
    type: select
    required: true
    order: 0
    options:
      - name: Critical
      - name: Major
      - name: Minor
  - key: surface
    name: Surface
    type: string
    order: 1
  - key: sentiment
    name: Sentiment
    type: number
    order: 2

Dry-run the apply first — it prints the exact request and validates the document locally without touching the board — then apply for real:

tix board schema apply

tix board schema apply <board-id> -f board.yaml --dry-run
tix board schema apply <board-id> -f board.yaml

3 · Verify the shape

Read the live schema back to confirm columns and fields landed. Export it as YAML to diff against the file in your repo:

tix board schema / fields

tix board schema <board-id> --yaml     # full schema (columns + fields)
tix board fields <board-id>            # just the custom fields + types

4 · Seed some tickets

Drop in a few tickets with typed field values. For a real backlog, pipe a batch on stdin so it is one atomic write:

tix ticket create

tix ticket create --board <board-id> \
  --title "Checkout 500s on Safari" \
  --field severity=Critical --field surface=web

# or a whole batch:
cat backlog.ndjson | tix ticket create --board <board-id> -

The board is now live and typed. Point an agent at it next — Connect an agent.