Shell Scripting - Documentation

Wrap the Heyweek CLI in shell scripts to automate time tracking with loops, variables, and error handling.

Basic automation

A simple script that ensures a timer is running, starting one if it is not:

<span class="token shebang important">#!/bin/bash</span>
<span class="token comment"># start-if-idle.sh</span>

<span class="token comment"># If no timer is running, start one</span>
<span class="token keyword">if</span> <span class="token operator">!</span> hw timer status <span class="token operator">></span>/dev/null <span class="token operator"><span class="token file-descriptor important">2</span>></span><span class="token file-descriptor important">&amp;1</span><span class="token punctuation">;</span> <span class="token keyword">then</span>
  hw timer start <span class="token parameter variable">-d</span> <span class="token string">"Working"</span>
<span class="token keyword">fi</span>

Variables and captured output

Capture command output into variables and reuse it. hw project list can emit JSON, which is easy to parse with jq or the built-in -q filter:

<span class="token shebang important">#!/bin/bash</span>
<span class="token comment"># pick-project.sh</span>

<span class="token comment"># Find a project ID by name using the built-in jq filter</span>
<span class="token assign-left variable">PROJECT_ID</span><span class="token operator">=</span><span class="token variable"><span class="token variable">$(</span>hw project list <span class="token parameter variable">-q</span> <span class="token string">'.[] | select(.name == "Website") | .id'</span><span class="token variable">)</span></span>

<span class="token keyword">if</span> <span class="token punctuation">[</span> <span class="token parameter variable">-z</span> <span class="token string">"<span class="token variable">$PROJECT_ID</span>"</span> <span class="token punctuation">]</span><span class="token punctuation">;</span> <span class="token keyword">then</span>
  <span class="token builtin class-name">echo</span> <span class="token string">"Project not found"</span>
  <span class="token builtin class-name">exit</span> <span class="token number">1</span>
<span class="token keyword">fi</span>

<span class="token builtin class-name">echo</span> <span class="token string">"Logging time to project <span class="token variable">$PROJECT_ID</span>"</span>
hw log create <span class="token parameter variable">-d</span> <span class="token string">"Scripted work"</span> <span class="token parameter variable">-p</span> <span class="token string">"<span class="token variable">$PROJECT_ID</span>"</span> <span class="token parameter variable">-s</span> <span class="token string">"09:00"</span> <span class="token parameter variable">-e</span> <span class="token string">"10:00"</span>

Loops

Iterate over projects to create a log entry for each one:

<span class="token shebang important">#!/bin/bash</span>
<span class="token comment"># log-all-projects.sh</span>

<span class="token comment"># Read each project ID from the JSON output</span>
hw project list <span class="token parameter variable">--json</span> id,name <span class="token operator">|</span> jq <span class="token parameter variable">-r</span> <span class="token string">'.[].id'</span> <span class="token operator">|</span> <span class="token keyword">while</span> <span class="token builtin class-name">read</span> <span class="token parameter variable">-r</span> project_id<span class="token punctuation">;</span> <span class="token keyword">do</span>
  <span class="token builtin class-name">echo</span> <span class="token string">"Creating log for <span class="token variable">$project_id</span>"</span>
  hw log create <span class="token parameter variable">-d</span> <span class="token string">"Daily standup"</span> <span class="token parameter variable">-p</span> <span class="token string">"<span class="token variable">$project_id</span>"</span> <span class="token parameter variable">-s</span> <span class="token string">"09:00"</span> <span class="token parameter variable">-e</span> <span class="token string">"09:15"</span>
<span class="token keyword">done</span>

Error handling

Use set -e, exit codes, and a trap to fail safely:

<span class="token shebang important">#!/bin/bash</span>
<span class="token builtin class-name">set</span> <span class="token parameter variable">-euo</span> pipefail

<span class="token function-name function">handle_error</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token builtin class-name">echo</span> <span class="token string">"Error on line <span class="token variable">$1</span>"</span>
  <span class="token builtin class-name">exit</span> <span class="token number">1</span>
<span class="token punctuation">}</span>
<span class="token builtin class-name">trap</span> <span class="token string">'handle_error $LINENO'</span> ERR

<span class="token comment"># Make sure we are authenticated before doing anything</span>
<span class="token keyword">if</span> <span class="token operator">!</span> hw user ctx <span class="token operator">></span>/dev/null <span class="token operator"><span class="token file-descriptor important">2</span>></span><span class="token file-descriptor important">&amp;1</span><span class="token punctuation">;</span> <span class="token keyword">then</span>
  <span class="token builtin class-name">echo</span> <span class="token string">"Not authenticated. Please run 'hw auth login' first."</span>
  <span class="token builtin class-name">exit</span> <span class="token number">1</span>
<span class="token keyword">fi</span>

<span class="token comment"># Continue with authenticated commands</span>
hw timer start <span class="token parameter variable">-d</span> <span class="token string">"Scripted work"</span>

Conditional logic

Choose a description based on the time of day:

<span class="token shebang important">#!/bin/bash</span>
<span class="token comment"># smart-start.sh</span>

<span class="token keyword">if</span> hw timer status <span class="token operator">></span>/dev/null <span class="token operator"><span class="token file-descriptor important">2</span>></span><span class="token file-descriptor important">&amp;1</span><span class="token punctuation">;</span> <span class="token keyword">then</span>
  <span class="token builtin class-name">echo</span> <span class="token string">"Timer already running"</span>
<span class="token keyword">else</span>
  <span class="token assign-left variable">HOUR</span><span class="token operator">=</span><span class="token variable"><span class="token variable">$(</span><span class="token function">date</span> +%H<span class="token variable">)</span></span>
  <span class="token keyword">if</span> <span class="token punctuation">[</span> <span class="token string">"<span class="token variable">$HOUR</span>"</span> <span class="token parameter variable">-lt</span> <span class="token number">12</span> <span class="token punctuation">]</span><span class="token punctuation">;</span> <span class="token keyword">then</span>
    hw timer start <span class="token parameter variable">-d</span> <span class="token string">"Morning development"</span>
  <span class="token keyword">elif</span> <span class="token punctuation">[</span> <span class="token string">"<span class="token variable">$HOUR</span>"</span> <span class="token parameter variable">-lt</span> <span class="token number">17</span> <span class="token punctuation">]</span><span class="token punctuation">;</span> <span class="token keyword">then</span>
    hw timer start <span class="token parameter variable">-d</span> <span class="token string">"Afternoon tasks"</span>
  <span class="token keyword">else</span>
    hw timer start <span class="token parameter variable">-d</span> <span class="token string">"Evening work"</span>
  <span class="token keyword">fi</span>
<span class="token keyword">fi</span>

← Back to CLI scripting.