Reference

CLI Reference

Complete command reference for the tick CLI. Every mutation to TICK.md goes through the CLI to ensure validation, locking, and proper history logging.

Installation

npm install -g tick-md

# Verify installation
tick --version

Project Commands

`tick init`

Initialize a new Tick project in the current directory.

$ tick init [options]

Options:
  --name <name>        Project slug (default: directory name)
  --title <title>      Human-readable project title
  --workflow <states>  Comma-separated workflow states
                       (default: backlog,todo,in_progress,review,done)

Creates .tick/ directory, TICK.md, and tasks/ folder.

`tick status`

Display project overview with task counts and active agents.

$ tick status [options]

Options:
  --json    Output as JSON
  --quiet   Only show counts

$ tick status

┌─────────────────────────────────────┐
│  adgena-v2 · Adgena V2 Launch      │
├─────────┬───────────────────────────┤
│ backlog │ 12 tasks                  │
│ todo    │  8 tasks                  │
│ active  │  3 tasks (2 bots, 1 you) │
│ review  │  5 tasks                  │
│ done    │ 15 tasks                  │
└─────────┴───────────────────────────┘

`tick validate`

Validate TICK.md against the schema. Checks all task blocks for required fields, valid statuses, and reference integrity.

$ tick validate [options]

Options:
  --strict   Fail on warnings (not just errors)
  --fix      Auto-fix common issues (missing timestamps, etc.)

Task Commands

`tick add`

Create a new task.

$ tick add <title> [options]

Options:
  --priority <level>   urgent | high | medium | low (default: medium)
  --tags <tags>        Comma-separated tags
  --assign <agent>     Agent to assign (e.g., @claude-code)
  --depends-on <ids>   Comma-separated task IDs this depends on
  --detail             Create a detail file in tasks/
  --due <date>         Due date (ISO 8601 or natural language)
  --commit             Auto-commit after change (override config)
  --no-commit          Skip auto-commit even if config enables it

$ tick add "Build user auth" --priority high --tags backend,auth --assign @claude-code

✓ Created TASK-001: Build user auth
  Priority: high
  Tags: backend, auth
  Assigned: @claude-code
  Status: backlog

`tick claim`

Claim a task for the current agent. Acquires the file lock, sets claimed_by, transitions status to in_progress, and commits.

$ tick claim <task-id> [options]

Options:
  --as <agent>    Agent identifier (default: detected from git config or env)
  --force         Override existing claim (owner role only)
  --commit        Auto-commit after change (override config)
  --no-commit     Skip auto-commit even if config enables it

A task can only be claimed if claimed_by is null, all depends_on tasks are done, and the agent’s role permits the task’s tags.

`tick release`

Release a claim without changing status. Useful when an agent needs to hand off mid-work.

$ tick release <task-id> [options]

Options:
  --comment <msg>  Add a comment explaining why the task was released
  --commit         Auto-commit after change (override config)
  --no-commit      Skip auto-commit even if config enables it

`tick update`

Update task fields.

$ tick update <task-id> [options]

Options:
  --priority <level>   Change priority
  --tags <tags>        Replace tags
  --assign <agent>     Reassign
  --due <date>         Change due date
  --add-dep <id>       Add a dependency
  --rm-dep <id>        Remove a dependency

`tick done`

Mark a task as complete. Releases the claim and transitions status.

$ tick done <task-id> [options]

Options:
  --skip-review    Go directly to done (skip review state)
  --comment <msg>  Add a completion comment
  --commit         Auto-commit after change (override config)
  --no-commit      Skip auto-commit even if config enables it

`tick comment`

Add a comment to a task’s history log.

$ tick comment <task-id> <message> [options]

Options:
  --commit        Auto-commit after change (override config)
  --no-commit     Skip auto-commit even if config enables it

Example:
$ tick comment TASK-001 "JWT middleware done, working on refresh tokens"

Query Commands

`tick query`

Search and filter tasks.

$ tick query [options]

Options:
  --status <status>      Filter by status
  --priority <level>     Filter by priority
  --assigned <agent>     Filter by assignee
  --tag <tag>            Filter by tag
  --claimed              Show only claimed tasks
  --unclaimed            Show only unclaimed tasks
  --blocked              Show only blocked tasks
  --overdue              Show tasks past due date
  --sort <field>         Sort by field (priority, created, updated, due)
  --json                 Output as JSON
  --limit <n>            Limit results

$ tick query --status todo --priority high --tag frontend

TASK-012 · Redesign nav component (todo) high  tags:frontend,ui
TASK-018 · Add dark mode toggle (todo) high  tags:frontend,a11y

`tick context`

Assemble the full context package for a task. Designed for injection into LLM prompts.

$ tick context <task-id> [options]

Options:
  --format <fmt>   markdown | json | yaml (default: markdown)
  --include-deps   Include dependency task summaries
  --include-blocks Include blocked task summaries

$ tick context TASK-042

# Returns:
# - Task metadata (status, priority, assignee, etc.)
# - Full history log
# - Detail file content (if exists)
# - Dependency summaries
# - Agent registry snapshot

Agent Commands

`tick agent register`

$ tick agent register <name> [options]

Options:
  --type <type>     human | bot (default: bot)
  --roles <roles>   Comma-separated roles (e.g., engineer,tester)
  --trust <level>   owner | trusted | restricted | readonly (default: trusted)

`tick agent list`

List all registered agents and their current status.

$ tick agent list [--json]

Agent          Type   Roles          Status   Working On   Last Active
@gianni        human  owner,any      online   TASK-001     2m ago
@claude-code   bot    engineer       idle     -            5m ago
@content-bot   bot    copywriter     working  TASK-003     30s ago
@qa-bot        bot    tester         idle     -            15m ago

`tick agent heartbeat`

Update an agent’s last_active timestamp. Bots should call this periodically.

$ tick agent heartbeat [--as <agent>]

Git Integration

When git.auto_commit is enabled in .tick/config.yml (enabled by default), every CLI mutation automatically creates a git commit:

[tick] TASK-001 claimed by @claude-code
[tick] TASK-001 status: todo → in_progress
[tick] TASK-003 created: Write launch email
[tick] TASK-001 completed by @claude-code

Set git.auto_commit: false to disable automatic commits, or use the --no-commit flag on individual commands to skip auto-commit for specific operations. Conversely, use --commit to force auto-commit even when disabled in config.

Set git.auto_push: true to automatically push after each commit (useful for remote teams).

Environment Variables

Variable	Description	Default
`TICK_AGENT`	Default agent identity	Detected from git config
`TICK_DIR`	Path to Tick project root	Current directory
`TICK_LOCK_TIMEOUT`	Lock timeout in seconds	30
`TICK_AUTO_COMMIT`	Override auto-commit setting	From config
`TICK_JSON`	Force JSON output for all commands	false

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Validation error (schema, transition, or permission)
`3`	Lock conflict (another agent holds the lock)
`4`	Task not found
`5`	Dependency not met