Heyweek CLI Overview - Documentation

The Heyweek command-line interface (CLI) brings your Heyweek account to the terminal. Track time, manage projects and clients, edit work logs, and switch between workspaces without leaving your command line. It's built for developers and power users who prefer working from a terminal.

Key features

Secure authentication — OAuth 2.0 device flow with tokens stored securely in your system's credential store.
Time tracking — Start, check, and stop timers from the terminal.
Project and client management — Create, list, edit, and delete projects and clients.
Work logs — Create, list, edit, and delete detailed log entries.
Workspace support — Create, list, edit, and switch between multiple workspaces.
Cross-platform — Runs on macOS, Linux, and Windows.
Auto-updates — The CLI checks for new versions every 24 hours and you can upgrade in place.

Command groups

The CLI is organized into command groups, each with its own subcommands:

hw auth — Authentication: login, logout, renew.
hw timer — Time tracking: start, status, stop.
hw project — Projects: create, list, edit, delete.
hw client — Clients: create, list, edit, delete.
hw log — Work logs: create, list, edit, delete.
hw workspace — Workspaces: create, list, edit, info, switch.
hw pomo — Start a Pomodoro focus timer.
hw version — Print the CLI version.
hw upgrade — Upgrade the CLI to the latest version.

See the Commands Reference for the full list of subcommands and flags.

Authentication and security

The CLI signs you in using the OAuth 2.0 device flow — there is no password to type into the terminal. Run hw auth login and follow the prompt to authorize the CLI in your browser. Access tokens are stored securely in your operating system's credential store rather than in plaintext, and you can refresh an expired token with hw auth renew.

A quick example

A typical session looks like this:

<span class="token comment"># Log in to your account</span>
hw auth login

<span class="token comment"># Start tracking time with a description</span>
hw timer start <span class="token parameter variable">-d</span> <span class="token string">"Working on new feature"</span>

<span class="token comment"># Check the running timer</span>
hw timer status

<span class="token comment"># Stop the timer when you're done</span>
hw timer stop

Getting started

Install the CLI — Get it running on your system.
Log in — Run hw auth login to connect to your Heyweek account.
Learn the commands — Explore the available commands and flags.

You can display help for any command at any time with the --help flag:

hw <span class="token parameter variable">--help</span>
hw timer <span class="token parameter variable">--help</span>