Sign in Start free
Documentation

Troubleshooting

Common issues and solutions for the Heyweek CLI. After installation, if the hw command isn't recognized, your terminal probably can't find the binary on…

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

Common issues and solutions for the Heyweek CLI.

Installation Issues

Command Not Found

After installation, if the hw command isn't recognized, your terminal probably can't find the binary on its PATH.

bash 
<span class="token comment"># Check whether hw is on your PATH</span>
<span class="token function">which</span> hw        <span class="token comment"># macOS / Linux</span>
where.exe hw    <span class="token comment"># Windows (PowerShell)</span>

If it isn't found, the simplest fix is to reinstall with your package manager so the binary lands in a standard location:

bash 
<span class="token comment"># macOS / Linux (Homebrew)</span>
brew reinstall heyweek-cli

<span class="token comment"># Windows (Scoop)</span>
scoop uninstall heyweek
scoop <span class="token function">install</span> heyweek

On Debian/Ubuntu you can force a clean reinstall of the downloaded package:

bash 
<span class="token function">sudo</span> <span class="token function">apt</span> <span class="token function">install</span> <span class="token parameter variable">--reinstall</span> ./Heyweek_<span class="token operator">&lt;</span>version<span class="token operator">></span>_linux_<span class="token operator">&lt;</span>arch<span class="token operator">></span>.deb

After reinstalling, open a new terminal and confirm the CLI runs:

bash 
hw version

Keyring Errors on Linux

The CLI stores your auth token in the system keyring. On a minimal Linux setup the keyring backend may be missing — install one and log in again:

bash 
<span class="token function">sudo</span> <span class="token function">apt</span> <span class="token function">install</span> gnome-keyring   <span class="token comment"># Debian / Ubuntu</span>
<span class="token function">sudo</span> dnf <span class="token function">install</span> gnome-keyring   <span class="token comment"># Fedora</span>

hw auth login

Authentication Problems

Token Expired or Invalid

If a command reports that your token is expired or invalid, refresh it:

bash 
hw auth renew

If renewing doesn't work, log out and back in to start a fresh session:

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

You can confirm you're signed in and see your active context at any time:

bash 
hw workspace info

Resetting a Broken Config

If the config directory is corrupted or the CLI is stuck on bad state, remove it and authenticate again. Your token lives in the keyring, so this only clears local settings:

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

Timer Issues

Timer Already Running

If you try to start a timer while one is already running:

bash 
hw timer start
<span class="token comment"># Error: a timer is already running</span>

You have two options — stop the running timer first, or force a new one to start:

bash 
<span class="token comment"># Check what's currently running</span>
hw timer status

<span class="token comment"># Option 1: stop it</span>
hw timer stop

<span class="token comment"># Option 2: force-start a new timer</span>
hw timer start <span class="token parameter variable">--force</span>

Wrong Workspace

If commands are affecting the wrong workspace, check and switch your active context. Commands like hw timer, hw project, hw client, and hw log all act on the workspace shown by hw workspace info.

bash 
<span class="token comment"># See the active workspace</span>
hw workspace info

<span class="token comment"># List all workspaces you can access</span>
hw workspace list

<span class="token comment"># Switch to the right one</span>
hw workspace switch <span class="token parameter variable">--workspace</span> <span class="token string">"Acme Corp"</span>

Checking and Updating the CLI

Out-of-date versions can behave unexpectedly. The CLI checks for updates automatically about every 24 hours, but you can check and update manually at any time:

bash 
<span class="token comment"># See your installed version</span>
hw version

<span class="token comment"># Update to the latest release</span>
hw upgrade

Getting Help

Built-in Help

Every command has its own help text, available with the --help flag:

bash 
<span class="token comment"># General help</span>
hw <span class="token parameter variable">--help</span>

<span class="token comment"># Help for a command group</span>
hw timer <span class="token parameter variable">--help</span>

<span class="token comment"># Help for a specific subcommand</span>
hw timer start <span class="token parameter variable">--help</span>

Contact Support

If you're still stuck, reach out through our Contact & Support page and we'll help you out.

Next Steps