cli-reference.md

CLI Reference

Synopsis

tb [OPTIONS] [INPUT...]

Display Commands

Board View (default)

tb

Displays all items organized by board. This is the default when no options are provided.

Timeline View

tb --timeline
tb -i

Displays items in chronological order by creation date.

Archive View

tb --archive
tb -a

Displays archived (deleted) items.

Creating Items

Create Task

tb --task <description>
tb -t <description>

Creates a new task. Tasks can be checked off when completed.

Board assignment: Prefix board names with @:

tb --task @work "Review pull request"
tb --task @coding @review "Implement feature X"  # Multiple boards

Priority: Append p:N where N is 1 (normal), 2 (medium), or 3 (high):

tb --task "Fix critical bug" p:3        # High priority
tb --task @work "Update docs" p:2       # Medium priority

Combined example:

tb --task @work @urgent "Deploy hotfix" p:3

Create Note

tb --note <description>
tb -n <description>
tb --note

Creates a note. Notes are for reference and cannot be checked off.

When called without a description, opens your external editor ($EDITOR or $VISUAL, falling back to vi) to compose a note with a title and optional body. Lines starting with // are treated as comments and ignored. Delete all content to cancel.

tb --note "API endpoint: https://api.example.com"
tb --note @meetings "Standup at 9am daily"
tb --note                   # Opens editor for multi-line note

Modifying Items

Check/Uncheck Task

tb --check <id> [id...]
tb -c <id> [id...]

Toggles the completion status of tasks. Multiple IDs can be specified.

tb --check 1
tb --check 1 2 3

Begin/Pause Task

tb --begin <id> [id...]
tb -b <id> [id...]

Toggles the in-progress status of tasks. In-progress tasks are highlighted differently in the board view.

tb --begin 2
tb --begin 4 5

Star/Unstar Item

tb --star <id> [id...]
tb -s <id> [id...]

Toggles the starred status. Works on both tasks and notes.

tb --star 1
tb --star 1 3 5

Edit Description

tb --edit @<id> <new description>
tb -e @<id> <new description>

Edits an item's description. The ID must be prefixed with @.

tb --edit @3 "Updated task description"

Edit Note in Editor

tb --edit-note @<id>

Opens a note in your external editor ($EDITOR or $VISUAL, falling back to vi) for editing both the title and body. The first non-comment line becomes the title, and remaining lines become the body. Lines starting with // are comments and ignored. Delete all content to cancel.

tb --edit-note @5

Set Priority

tb --priority @<id> <1-3>
tb -p @<id> <1-3>

Sets task priority: 1 = normal, 2 = medium, 3 = high.

tb --priority @5 3    # Set to high priority
tb --priority @5 1    # Set to normal priority

Move to Board

tb --move @<id> <board>
tb -m @<id> <board>

Moves an item to a different board. Opens a board picker if the board name is omitted.

tb --move @3 work
tb --move @3 @personal   # @ prefix is optional for board name

Deleting and Restoring

Delete Item

tb --delete <id> [id...]
tb -d <id> [id...]

Moves items to the archive. They can be restored later.

tb --delete 4
tb --delete 1 2 3

Restore from Archive

tb --restore <id> [id...]
tb -r <id> [id...]

Restores archived items back to the active board.

tb --restore 4
tb --restore 10 11 12

Clear Completed

tb --clear

Permanently deletes all completed (checked) tasks from all boards.

Searching and Filtering

Find Items

tb --find <search term>
tb -f <search term>

Searches for items containing the search term in their description.

tb --find documentation
tb --find "pull request"

List by Attributes

tb --list <attributes>
tb -l <attributes>

Filters items by one or more attributes:

Attribute	Description
pending	Incomplete tasks
done	Completed tasks
task	All tasks
note	All notes
starred	Starred items

tb --list pending
tb --list done starred
tb --list task pending    # Pending tasks only

Clipboard

Copy to Clipboard

tb --copy <id> [id...]
tb -y <id> [id...]

Copies item descriptions to the system clipboard. Multiple items are joined with newlines.

tb --copy 1
tb --copy 1 2 3

Server Commands

These commands are used for syncing with a remote server. See Sync & Encryption for details.

Register Account

tb --register [OPTIONS]

Creates a new account on the sync server. Prompts interactively for missing values.

Option	Description
--server <url>	Server URL
--username <name>	Username
--email <email>	Email address
--password <pass>	Password (prompted securely if omitted)

# Fully interactive (recommended)
tb --register

# Partial - prompts for password
tb --register --server https://taskbook.example.com --username alice --email alice@example.com

Login

tb --login [OPTIONS]

Logs in to an existing account. Prompts interactively for missing values.

Option	Description
--server <url>	Server URL
--username <name>	Username
--password <pass>	Password (prompted securely if omitted)
--key <base64>	Encryption key from registration

# Fully interactive
tb --login

# With server specified
tb --login --server https://taskbook.example.com

Logout

tb --logout

Logs out and deletes stored credentials. Sync is disabled and the client returns to local-only mode.

Status

tb --status

Shows current sync status, server URL, and whether credentials are saved.

Migrate Local Data

tb --migrate

Pushes existing local data to the server. Use this after registering to upload your existing tasks.

Global Options

Custom Taskbook Directory

tb --taskbook-dir <path>

Use a custom directory for storing taskbook data instead of ~/.taskbook/.

tb --taskbook-dir ~/work-tasks --task "Work item"

Can also be set via environment variable:

export TASKBOOK_DIR=~/work-tasks
tb --task "Work item"

CLI Mode

tb --cli

Runs in non-interactive CLI mode, printing output to stdout instead of launching the interactive TUI. Useful for scripting or piping output.

Help

tb --help
tb -h

Displays help message with all available options.

Version

tb --version
tb -v

Displays the installed version.

Examples

# Daily workflow
tb                                    # View boards
tb --task @work "Code review"         # Create task
tb --begin 1                          # Start working
tb --check 1                          # Mark done

# Organize tasks
tb --task @personal "Buy groceries" p:2
tb --star 3
tb --move @3 shopping

# Search and filter
tb --find meeting
tb --list pending starred
tb --timeline

# Cleanup
tb --delete 5 6 7
tb --clear
tb --archive                          # View deleted items
tb --restore 5                        # Oops, restore one

# Server sync
tb --register
tb --migrate
tb --status