CLI Command Reference

Use this page as your day-to-day command reference.

Recommended order

1. Authenticate
2. Link repository (or workspace)
3. Sync
4. Review entries in the app

Command index

Authentication

workrail auth login
workrail auth status
workrail auth logout
# alias:
workrail login

Typical use cases

• New machine setup: run workrail auth login
• Auth issue triage: run workrail auth status
• Account switch or shared machine cleanup: run workrail auth logout, then workrail auth login

Repository linking

workrail link
workrail repos sync
workrail repos list
workrail unlink

Keep one repository linked to the correct project before syncing.

Status and diagnostics

workrail status
workrail status --json
workrail doctor
workrail doctor --json
workrail permissions
workrail update --check

Workspace commands

Use workspaces when you have multiple repos inside one parent folder.

workrail workspace add ~/Projects --depth 8
workrail workspace list
workrail workspace remove

Notes:

• Workspace linking is intentionally no-backfill
• New repos under that folder are discovered on future syncs
• Prefer workspace mode for monorepo + service-repo setups

Syncing

workrail sync
workrail sync --since 7d
workrail sync --catchup
workrail sync --catchup --catchup-days 4
workrail sync --max-runtime-minutes 10
workrail sync --json

Best practice: run workrail sync after your main coding block (for example once daily), then quickly tighten high-impact entries in the app.

Notes:

• Trial accounts are forward-only and do not support historical backfill.
• Pro accounts can backfill up to 30 days.
• Catchup mode is resumable; default window is 14 days.
• Use --catchup-days <n> to scope catchup (1 to 30 days on Pro).
• Large backlogs are processed in chunks over multiple runs.
• If rate limited, the CLI saves progress and continues on future sync runs.

Manual entry creation

Use workrail entry add to create achievement entries for work that isn't captured by git sync:

workrail entry add

This opens an interactive workflow:

1. Select project - Choose which project this entry belongs to
2. Title - What did you achieve?
3. Category - Feature, Bug Fix, Technical Decision, Learning, Mentorship, Meeting, or Other
4. Impact - Rate from 1 (minimal) to 5 (critical)
5. Tags - Comma-separated keywords (e.g., "redis, caching, api")
6. Description - Opens your preferred editor with a template

When to use manual entries

• Design decisions and architecture discussions
• Mentorship and code review sessions
• Team meetings with outcomes
• Learning and skill development
• Non-code contributions (documentation, process improvements)

Tips for good entries

• Write for your future self (6 months from now)
• Include context: what was the problem?
• Describe what changed and why it mattered
• Add concrete outcomes or metrics when possible

Autosync

workrail autosync enable
workrail autosync status
workrail autosync status --json
workrail autosync disable

Use autosync on your primary development machine to reduce manual overhead. If you omit --interval, autosync defaults to 240 minutes (4 hours).

Command help behavior

• Running workrail with no arguments shows top-level help.
• Running subcommand groups without a subcommand shows usage guidance (for example workrail repos or workrail autosync).
• Unknown commands return an error plus a suggestion.

Summary commands

workrail summary daily
workrail summary weekly
workrail summary --date 2026-02-11
workrail summary --from 2026-02-01 --to 2026-02-20
workrail summary --since 20d

Daily and date-based summaries use your local machine timezone so results match your actual day. Use --from/--to for inclusive date windows, and note custom summary windows are capped at 90 days.

Practical workflows

First-time setup

workrail auth login
workrail link
workrail sync

Optional Pro backfill after setup:

workrail sync --since 7d

Daily workflow

workrail sync

If sync quality looks weak

1. Improve commit subject clarity.