# Define a board — artifacts.md docs

> A step-by-step guide: create a board, give it a typed schema from board.yaml, verify the shape, and seed tickets — in under two minutes.

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  -f board.yaml --dry-run
tix board schema apply  -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  --yaml     # full schema (columns + fields)
tix board fields             # 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  \
  --title "Checkout 500s on Safari" \
  --field severity=Critical --field surface=web

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

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

← PreviousEphemeral boardsNext →Connect an agent