Configure Project Boards from the CLI

Everything you can do in the board settings dialog can be done from the CLI, which is handy for scripts and AI agents. Changes appear live in any open project window and sync to your other devices like edits made in the app.

Find the ids

Board and column ids are created by the app, never by you. List them first:

notecove project board list PROJ
notecove project board show PROJ <board-id>

notecove project show PROJ --json includes the same data under boards. Add --json to any board command for machine-readable output.

Create a board

A state-based board gets one column per project state automatically:

notecove project board create PROJ --name "Flow"

A custom board is defined by a JSON file listing its columns. Each column has a name and an optional filter; a task shows up in every column whose filter it matches.

[
  { "name": "Urgent bugs", "filter": { "priorities": [1, 2], "isTerminal": false } },
  { "name": "Blocked", "color": "#EF4444", "filter": { "blockerFilter": ["has-uncompleted"] } },
  { "name": "Everything else" }
]

notecove project board create PROJ --name "Triage" --type custom --columns-file columns.json

The command prints the new board with its generated ids. Run notecove project board create --json-format for the full list of column fields and filter keys.

Filters

Key	Matches tasks whose…
`stateIds`	state is one of the listed state ids
`typeIds`	type is one of the listed type ids (`__no_type__` for untyped)
`tagIds`	hashtags include all of the listed tags
`excludeTagIds`	hashtags include none of the listed tags (a tag can’t be in both `tagIds` and `excludeTagIds`)
`priorities`	priority is one of the listed values, 1 to 5
`blockerFilter`	blocker status is one of `none`, `all-completed`, `has-uncompleted`
`isTerminal`	state is terminal (`true`) or not (`false`)
`depths`	position in the task tree is one of `root`, `leaf`, `parent`, `has-parent`, `has-grandchildren`, `has-great-grandchildren`

State and type ids are checked against the project; an unknown id is rejected. Filter keys the CLI doesn’t know about (for example ones added by a newer app) are saved unchanged and reported as a warning.

Edit a board

# Rename
notecove project board change PROJ <board-id> --name "Triage v2"

# Add a column with a filter, using flags instead of JSON
notecove project board change PROJ <board-id> --add-column "P1" --filter-priority 1 --no-filter-terminal

# Change or clear a column's filter
notecove project board change PROJ <board-id> --update-column <column-id> --filter-priority 1,2
notecove project board change PROJ <board-id> --update-column <column-id> --clear-filter

# Rename, recolor, or reorder a column
notecove project board change PROJ <board-id> --update-column <column-id> --column-name "Hot" --color "#EF4444" --order 0

# Remove a column, or the whole board
notecove project board change PROJ <board-id> --remove-column <column-id>
notecove project board delete PROJ <board-id>

Each change call does one thing: either a board-level change (--name, --columns-file) or a single column operation.

--columns-file replaces the board’s entire column set. To keep a column’s identity, include its existing id in the file; columns without a matching id are created fresh. Changing a board’s type (--type) requires --columns-file, because state columns and filter columns aren’t interchangeable.

For a filter the flags don’t cover, pass raw JSON with --filter-json '{"priorities":[1]}'. It is merged with any filter flags, and flags win for the same key.

Sort a column

A column can order its cards by up to two keys instead of by hand: priority, created, modified, type or tag. Repeat --sort for a second key; each takes an optional :asc or :desc (default asc, which means highest priority, oldest date, type list order or smallest tag first).

# Highest priority first, then oldest first
notecove project board change PROJ <board-id> --update-column <column-id> --sort priority --sort created

# Newest first, on a new column
notecove project board change PROJ <board-id> --add-column "Recent" --sort modified:desc

# By a tag such as #pr-83095: the smallest matching tag wins; mode is numeric (default), natural or lexical
notecove project board change PROJ <board-id> --update-column <column-id> --sort tag --sort-tag-prefix "#pr-" --sort-tag-mode numeric

# Back to manual order
notecove project board change PROJ <board-id> --update-column <column-id> --clear-sort

Tasks without a value go last. A sorted column ignores manual positions. Changing a board’s type removes and re-adds its columns, so their sorts are lost; set them again afterwards.

Project settings and field visibility

notecove project change PROJ --name "New name" --description "Shown in the project list"
notecove project change PROJ --default-folder <folder-id>
notecove project change PROJ --field-visibility assignee=true --field-visibility tags=false

Field names are slug, typeBadge, tags, folderPath, priority, modifiedTime, relationships, discussion and assignee.