Sign in Start free
Documentation

CLI Configuration

Configure the Heyweek CLI to match your workflow. This guide covers authentication, the config file, workspace context, environment variables, and how…

Last updated:
Tags:
#cli#command-line#terminal

Configure the Heyweek CLI to match your workflow. This guide covers authentication, the config file, workspace context, environment variables, and how updates work.

Initial Setup

After installing the CLI, the first step is connecting it to your Heyweek account.

Authentication

The CLI uses an OAuth 2.0 device flow — there is no password login. Run:

bash 
hw auth login

This command will:

  1. Show a device code and open (or link to) the Heyweek authorization page in your browser
  2. Wait for you to approve the request while signed in to your account
  3. Store the resulting token securely in your operating system's keyring
  4. Confirm the workspace context the CLI is now operating in

Verify Authentication

Check which workspace and device are currently active:

bash 
hw workspace info

If your token has expired, refresh it without a full re-login:

bash 
hw auth renew

To sign out and remove the stored token:

bash 
hw auth <span class="token builtin class-name">logout</span>

Configuration File

The CLI stores non-sensitive settings in a TOML config file. Your authentication token is not kept here — it lives in your system keyring (Keychain on macOS, Credential Manager on Windows, and the Secret Service / gnome-keyring on Linux). The config file only records which workspace context the CLI is currently using.

bash 
<span class="token comment"># Config file location</span>
~/.config/heyweek/config.toml

<span class="token comment"># View it</span>
<span class="token function">cat</span> ~/.config/heyweek/config.toml

A typical config file looks like this:

toml 
[default]
device_name = "my-laptop"
workspace_name = "My Workspace"
workspace_id = "workspace-id"

You normally don't edit this file by hand — the CLI updates it for you when you switch workspaces. If it ever becomes invalid, you can remove the config directory and log in again:

bash 
<span class="token function">rm</span> <span class="token parameter variable">-rf</span> ~/.config/heyweek/
hw auth login

Workspace Context

The CLI operates against one active workspace at a time. The active workspace is recorded in the config file and applied to commands like hw timer, hw project, hw client, and hw log.

List Available Workspaces

bash 
hw workspace list

Switch Workspace

Switch interactively, or name the workspace directly with -w/--workspace:

bash 
<span class="token comment"># Interactive selection</span>
hw workspace switch

<span class="token comment"># Switch by name</span>
hw workspace switch <span class="token parameter variable">--workspace</span> <span class="token string">"Personal Projects"</span>

Inspect the Active Workspace

bash 
hw workspace info

Environment Variables

You can override the stored token by exporting it in your environment. This is useful in CI or other non-interactive contexts where the keyring isn't available:

bash 
<span class="token comment"># Provide the auth token directly</span>
<span class="token builtin class-name">export</span> <span class="token assign-left variable">HEYWEEK_TOKEN</span><span class="token operator">=</span>your-token-here

To make this permanent, add the export line to your shell profile (~/.zshrc, ~/.bashrc, or the equivalent for your shell).

Shell Aliases

The CLI does not have its own alias command. If you run the same commands often, define your own shell aliases — they work with any command, not just Heyweek:

bash 
<span class="token comment"># Add to ~/.zshrc or ~/.bashrc</span>
<span class="token builtin class-name">alias</span> <span class="token assign-left variable">hts</span><span class="token operator">=</span><span class="token string">'hw timer start'</span>
<span class="token builtin class-name">alias</span> <span class="token assign-left variable">htp</span><span class="token operator">=</span><span class="token string">'hw timer stop'</span>
<span class="token builtin class-name">alias</span> <span class="token assign-left variable">hst</span><span class="token operator">=</span><span class="token string">'hw timer status'</span>
<span class="token builtin class-name">alias</span> <span class="token assign-left variable">hpl</span><span class="token operator">=</span><span class="token string">'hw project list'</span>

After adding them, reload your shell (source ~/.zshrc) and use them like any other command:

bash 
hts <span class="token parameter variable">-d</span> <span class="token string">"Working on feature"</span>

Updates

The CLI automatically checks for a newer version roughly every 24 hours and lets you know when one is available. When you're ready to update, run:

bash 
hw upgrade

Check the version you currently have installed with:

bash 
hw version

Next Steps