Skip to content

signboard-cli.md

Latest commit

 

History

History
401 lines (277 loc) · 9.16 KB

signboard-cli.md

File metadata and controls

401 lines (277 loc) · 9.16 KB

Signboard CLI

This guide covers the Signboard command-line interface.

Table of Contents

How to Run It

On macOS and Linux, the desktop app can install the Signboard wrapper from Help > Install Signboard CLI. Sorry for those of you on Windows, but you can use WSL (it is good, and you should!).

Once installed, try it out!

signboard --help

If you want to run this at its full path...

Packaged app executable

/Applications/Signboard.app/Contents/MacOS/Signboard --help

Other packaged examples:

  • Linux AppImage: ./signboard_*.AppImage --help

Choose a Board

Most commands operate on one board root. To simplify subsequent calls, you can first "choose a board" for Signboard CLI to interact with.

signboard use /Path/To/Board

You can always supply a differen't board's path with --board.

Example:

signboard lists --board /Path/To/Board

You can print the current chosen board by running:

signboard use

Command Groups

The CLI is organized into six command groups:

  • lists
  • cards
  • archive
  • settings
  • import

lists

List, create, or rename lists.

signboard lists
signboard lists --include-archive
signboard lists create "Waiting"
signboard lists rename "Waiting" "Blocked"

Notes:

  • signboard lists excludes XXX-Archive unless you add --include-archive.
  • Newly created lists get an ordering prefix and a unique suffix automatically. This helps with name collisions.

cards

List, read, create, or edit cards.

List cards

signboard cards
signboard cards "To do"
signboard cards --search release
signboard cards --label Urgent
signboard cards --label Urgent --label Writing --label-mode all
signboard cards --due today
signboard cards --due next:7 --due-source any
signboard cards --due overdue --task-status open
signboard cards --sort due
signboard cards --limit 10
signboard cards --include-archive

Useful filters:

  • --list <ref> repeatable
  • --label <ref> repeatable
  • --label-mode any|all
  • --search <query>
  • --due today|tomorrow|overdue|upcoming|this-week|next:7|next:14|next:30|YYYY-MM-DD|none
  • --due-source any|card|task
  • --task-status open|any
  • --sort list|due|title|updated
  • --limit <n>
  • --include-archive

Read one card

signboard cards read --card ab123
signboard cards read --list Doing --card "Ship release notes"
signboard cards read --card 003-ship-release-notes-ab123.md

cards read always returns JSON so it is safe for scripts and agents.

Create a card

signboard cards create --list "To do" --title "Ship release notes"
signboard cards create --list "To do" --title "Write announcement" --due 2026-04-10
signboard cards create --list "To do" --title "Draft copy" --label Writing --label Marketing

Create options:

  • --list <list-ref> required
  • --title <title> required
  • --body <text>
  • --body-file <path>
  • --due <YYYY-MM-DD|none>
  • --label <ref> repeatable

Using a body file means you can make your commands much shorter and import previous content faster, potentially.

Example with a body file:

signboard cards create \
  --list "To do" \
  --title "Launch checklist" \
  --body-file ./launch-checklist.md

Edit a card

signboard cards edit --card ab123 --title "Ship v1.2.0"
signboard cards edit --card ab123 --due 2026-04-12
signboard cards edit --card ab123 --due none
signboard cards edit --card ab123 --move-to Doing
signboard cards edit --card ab123 --append-body $'\n\nFollow up with QA.'
signboard cards edit --card ab123 --set-label Urgent
signboard cards edit --card ab123 --add-label Docs --remove-label Backlog

Edit options:

  • --card <card-ref> required
  • --list <list-ref> optional disambiguation when card refs are not unique
  • --title <title>
  • --body <text>
  • --body-file <path>
  • --append-body <text>
  • --due <YYYY-MM-DD|none>
  • --set-label <ref> repeatable, replaces all labels
  • --add-label <ref> repeatable
  • --remove-label <ref> repeatable
  • --move-to <list-ref>

Reference Matching

The CLI accepts flexible references so you do not always need exact filenames.

List refs

Lists can be matched by:

  • directory name
  • display name
  • unique partial match of either

Example:

signboard lists rename wait blocked

If wait matches exactly one list, the command succeeds. If it matches multiple lists, the CLI fails with an ambiguity error.

Card refs

Cards can be matched by:

  • filename
  • 5-character card id
  • title
  • unique partial match of any of those

Examples:

signboard cards read --card ab123
signboard cards read --card "Ship release notes"
signboard cards read --card ship-release

Label refs

Labels can be matched by:

  • label id
  • label name
  • unique partial match

Machine-Readable Output for Agents

Prefer --json whenever you need reliable parsing.

Examples:

signboard lists --json
signboard cards --due next:7 --json
signboard archive cards --search launch --json
signboard settings --json
signboard import obsidian --source ~/Vault/Boards --json

Recommended agent workflow:

  1. Pass --board <path> instead of changing global state with signboard use.
  2. Read before write when references may be ambiguous.
  3. Use --json for reads and verification.
  4. Use exact list or card references when possible.

Common Workflows

Find cards due this week

signboard cards --due this-week --sort due --json

Find cards with overdue checklist items

signboard cards --due overdue --due-source task --task-status open --json

Create a card and move it later

signboard cards create --list Backlog --title "Write release post" --label Docs --due 2026-04-08
signboard cards edit --card "Write release post" --move-to Doing

Search by title or body text

signboard cards --search release

Filter by multiple labels

signboard cards --label Docs --label Review --label-mode all

Show recently updated cards

signboard cards --sort updated --limit 20 --json

Archive Workflows

The CLI can find and restore archived cards and lists.

List archived cards

signboard archive cards
signboard archive cards --search launch --json

List archived lists

signboard archive lists
signboard archive lists --search done --json

Read one archived entry

signboard archive read --kind card --entry ab123
signboard archive read --kind list --entry "Done"

Restore an archived card

signboard archive restore-card --card ab123 --to-list "To do"

The --card value can be an archive path, archived filename, card id, or title as long as it resolves uniquely.

Restore an archived list

signboard archive restore-list --list "Completed Sprint"
signboard archive restore-list --list "Completed Sprint" --as 010-Completed-Sprint-restored

If you use --as, provide the directory name you want for the restored list.

Settings and Imports

Read board settings

signboard settings
signboard settings --json

This returns the board settings Markdown document, including labels, color scheme data, notifications, and tooltip settings.

Current CLI editing support is intentionally narrow.

For label editing, color-scheme changes, and notification changes, use the desktop app or edit board-settings.md carefully.

Import from Trello

Trello will give you a JSON export of any board. You can import it into the current board.

signboard import trello --file ~/Downloads/trello-export.json

Import from Obsidian

You can import any Markdown files. But also Signboard supports the frontmatter and metadata created by most of the leading popular community kanban plugins for Obsidian.

signboard import obsidian --source ~/Vault/Kanban.md
signboard import obsidian --source ~/Vault/Boards --source ~/Vault/ExtraBoard.md

Import from Tasks.md

Tasks.md is one of the most popular Markdown kanban apps on GitHub. You can import data created with that app into Signboard.

signboard import tasksmd --source ~/Projects/MyTasksBoard

All import commands support --json.

Markdown and Due-Date Conventions

Cards are Markdown files with frontmatter. The CLI reads and writes that structure for you. So you don't need to worry about that unless you are supplying your own files.

Card due dates

Use ISO local dates:

YYYY-MM-DD

Examples:

  • 2026-04-02
  • 2026-04-14
  • none to clear the card due date

Checklist due dates

Checklist items may also contain due dates in the body:

- [ ] (due: 2026-04-05) Review screenshots
- [x] (due: 2026-04-01) Draft release notes

These task due dates participate in due-date filtering and temporal views.