Advanced Workflows - Documentation

Power-user techniques for the Heyweek CLI: shell aliases, scripting patterns, and troubleshooting — all built from real commands.

Shell aliases

The CLI doesn't manage aliases for you, but your shell does. Add shortcuts for the commands you run most.

<span class="token comment"># Add to ~/.zshrc or ~/.bashrc</span>
<span class="token builtin class-name">alias</span> <span class="token assign-left variable">hws</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">hwx</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">hwt</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">hwl</span><span class="token operator">=</span><span class="token string">'hw log list'</span>
<span class="token builtin class-name">alias</span> <span class="token assign-left variable">hwp</span><span class="token operator">=</span><span class="token string">'hw project list'</span>

You can also wrap multiple commands in a shell function:

<span class="token comment"># Switch task: stop the current timer and start a new one</span>
<span class="token function-name function">hwswitch</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  hw timer start <span class="token parameter variable">-f</span> <span class="token parameter variable">-d</span> <span class="token string">"<span class="token variable">$1</span>"</span>
  hw timer status
<span class="token punctuation">}</span>

Scripting patterns

Loop over projects

<span class="token shebang important">#!/bin/bash</span>
<span class="token comment"># Print the project list, then a snapshot of recent logs.</span>

hw project list
<span class="token builtin class-name">echo</span> <span class="token string">"---"</span>
hw log list <span class="token parameter variable">-L</span> <span class="token number">20</span>

Log several time blocks at once

<span class="token shebang important">#!/bin/bash</span>
<span class="token comment"># Create multiple log entries from a here-doc.</span>

<span class="token keyword">while</span> <span class="token assign-left variable"><span class="token environment constant">IFS</span></span><span class="token operator">=</span><span class="token string">'|'</span> <span class="token builtin class-name">read</span> <span class="token parameter variable">-r</span> desc start end<span class="token punctuation">;</span> <span class="token keyword">do</span>
  <span class="token punctuation">[</span> <span class="token parameter variable">-z</span> <span class="token string">"<span class="token variable">$desc</span>"</span> <span class="token punctuation">]</span> <span class="token operator">&amp;&amp;</span> <span class="token builtin class-name">continue</span>
  hw log create <span class="token parameter variable">-d</span> <span class="token string">"<span class="token variable">$desc</span>"</span> <span class="token parameter variable">-s</span> <span class="token string">"<span class="token variable">$start</span>"</span> <span class="token parameter variable">-e</span> <span class="token string">"<span class="token variable">$end</span>"</span>
<span class="token keyword">done</span> <span class="token operator">&lt;&lt;</span><span class="token string">'EOF'
Team meeting|09:00|10:00
Feature development|10:00|12:00
Code review|13:00|15:00
EOF</span>

Combine commands

<span class="token comment"># Stop the current timer, then immediately list today's logs</span>
hw timer stop <span class="token operator">&amp;&amp;</span> hw log list <span class="token parameter variable">-L</span> <span class="token number">10</span>

Troubleshooting

Check your version and update

<span class="token comment"># Show the installed CLI version</span>
hw version

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

Re-authenticate

If commands start failing with auth errors, refresh your session:

<span class="token comment"># Refresh your token</span>
hw auth renew

<span class="token comment"># If that doesn't work, log out and back in</span>
hw auth <span class="token builtin class-name">logout</span>
hw auth login

<span class="token comment"># Confirm you're authenticated and in the right context</span>
hw user ctx

Get help on any command

Every command supports --help:

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

← Back to CLI workflows.