CLI Commands Reference
A reference for every Heyweek CLI command group, its subcommands, and key flags. The commands are identical across macOS, Linux, and Windows.
A reference for every Heyweek CLI command group, its subcommands, and key flags. The commands are identical across macOS, Linux, and Windows.
Command structure
All commands follow this pattern:
bash
hw <span class="token punctuation">[</span>command<span class="token punctuation">]</span> <span class="token punctuation">[</span>subcommand<span class="token punctuation">]</span> <span class="token punctuation">[</span>flags<span class="token punctuation">]</span>hw— the main CLI executable.command— a command group such asauth,timer, orproject.subcommand— a specific action within the group, such asstartorlist.flags— options that modify behavior.
Getting help
Every command has its own help text, available with the --help flag:
bash
hw <span class="token parameter variable">--help</span>
hw timer <span class="token parameter variable">--help</span>
hw timer start <span class="token parameter variable">--help</span>
Authentication (hw auth)
Manage authentication and your access token. The CLI uses the OAuth 2.0 device flow, so there is no password to enter.
bash
hw auth login <span class="token comment"># Log in to your Heyweek account</span>
hw auth <span class="token builtin class-name">logout</span> <span class="token comment"># Log out of your Heyweek account</span>
hw auth renew <span class="token comment"># Refresh your access token</span>View detailed auth documentation →
Timer (hw timer)
Control time tracking.
bash
hw timer start <span class="token comment"># Start a timer</span>
hw timer status <span class="token comment"># Show the current timer status</span>
hw timer stop <span class="token comment"># Stop the running timer</span>Flags for hw timer start:
-d, --description string— description of the timer.-f, --force— force-start a timer.
View detailed timer documentation →
Projects (hw project)
Manage projects in your workspace.
bash
hw project create <span class="token comment"># Create a new project</span>
hw project list <span class="token comment"># List projects</span>
hw project edit <span class="token comment"># Edit a project</span>
hw project delete <span class="token comment"># Delete a project</span>Key flags:
hw project create—-n, --name string(project name),-i, --clientId string(client ID).hw project list—-l, --limit uint32(results per page, default 25),-p, --page uint32(page, default 1),--json strings(output JSON with the specified fields),-q, --jq expression(filter JSON output with a jq expression).hw project edit—-i, --id string(project ID),-n, --name string(new name).hw project delete—-i, --id string(project ID).
View detailed project documentation →
Clients (hw client)
Manage clients in your workspace.
bash
hw client create <span class="token comment"># Create a client</span>
hw client list <span class="token comment"># List clients</span>
hw client edit <span class="token comment"># Update a client</span>
hw client delete <span class="token comment"># Delete a client</span>Key flags:
hw client create—-n, --name string(client name).hw client list—-l, --limit int32(results per page),-p, --page int32(page).hw client edit—-i, --id string(client ID),-n, --name string(new name).hw client delete—-i, --id string(client ID).
View detailed client documentation →
Work logs (hw log)
Manage work log entries.
bash
hw log create <span class="token comment"># Create a log entry</span>
hw log list <span class="token comment"># List active workspace logs</span>
hw log edit <span class="token comment"># Edit a log entry</span>
hw log delete <span class="token comment"># Delete log entries</span>Key flags:
hw log create—-d, --description string,-p, --project string(project ID),-s, --start-time stringand-e, --end-time string(YYYY-MM-DD HH:MMorHH:MM).hw log list—-L, --limit int32(results per page),-p, --page int32(page).hw log edit—-l, --log-id string(log ID),-d, --description string,-p, --project string,-s, --start-time string,-e, --end-time string.hw log delete—--ids stringArray(IDs to delete, separated by commas).
Example:
bash
hw log create <span class="token parameter variable">-d</span> <span class="token string">"Bug fix"</span> --start-time <span class="token string">"2024-01-15 09:00"</span> --end-time <span class="token string">"2024-01-15 17:00"</span>View detailed log documentation →
Workspaces (hw workspace)
Create, switch between, and manage workspaces.
bash
hw workspace create <span class="token comment"># Create a new workspace</span>
hw workspace list <span class="token comment"># List workspaces</span>
hw workspace edit <span class="token comment"># Edit a workspace</span>
hw workspace info <span class="token comment"># Show the current workspace info</span>
hw workspace switch <span class="token comment"># Switch the active workspace</span>Key flags:
hw workspace create—-n, --name string(workspace name).hw workspace list—-l, --limit int32(results per page),-p, --page int32(page).hw workspace edit—-i, --id string(workspace ID),-n, --name string(new name).hw workspace switch—-w, --workspace string(workspace name).
View detailed workspace documentation →
Pomodoro (hw pomo)
Start a Pomodoro focus timer in the terminal, with an inline progress view.
bash
hw pomo <span class="token comment"># Classic Pomodoro: 25 min work, 5 min break, 4 cycles</span>
hw pomo <span class="token number">30</span> <span class="token comment"># 30-minute work session (30m also works)</span>
hw pomo <span class="token number">45</span>/5 <span class="token comment"># 45 min work, 5 min break</span>
hw pomo <span class="token number">45</span>/5*2 <span class="token comment"># 45/5, repeated for 2 cycles</span>Flags:
-d, --description string— description of the work session.-p, --project string— project ID to log the session against.-f, --force— skip interactive prompts.-s, --silent— silent mode (no notifications or sounds).
Version (hw version)
Print the CLI version.
bash
hw version
hw version <span class="token parameter variable">-o</span> json <span class="token comment"># Output as JSON</span>
hw version <span class="token parameter variable">-o</span> yaml <span class="token comment"># Output as YAML</span>
hw version <span class="token parameter variable">-o</span> short <span class="token comment"># Short output</span>The -o, --output flag accepts json, pretty, short, or yaml (default pretty).
Upgrade (hw upgrade)
Upgrade the CLI to the latest available version.
bash
hw upgrade <span class="token comment"># Upgrade to the latest version</span>
hw upgrade <span class="token parameter variable">-f</span> <span class="token comment"># Force upgrade even if already on the latest version</span>The -f, --force flag forces the upgrade.