Sign in Start free
Documentation

CLI Scripting

The Heyweek CLI (`hw`) is designed to be scriptable. Because every command is a plain executable that reads flags and writes to standard output, you can wrap it

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

The Heyweek CLI (hw) is designed to be scriptable. Because every command is a plain executable that reads flags and writes to standard output, you can wrap it in shell, Python, or Node.js scripts to automate your time-tracking workflow.

Basics

The CLI is scriptable

Every command follows the same hw <command> <subcommand> [flags] pattern and can be called non-interactively from a script:

bash 
<span class="token comment"># Start a timer with a description</span>
hw timer start <span class="token parameter variable">-d</span> <span class="token string">"Automated task"</span>

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

<span class="token comment"># Stop the running timer</span>
hw timer stop

Exit codes

The CLI returns 0 on success and a non-zero exit code on failure. Use the exit code to branch in your scripts instead of parsing messages:

bash 
<span class="token shebang important">#!/bin/bash</span>
<span class="token keyword">if</span> hw timer start <span class="token parameter variable">-d</span> <span class="token string">"Automated task"</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 started successfully"</span>
<span class="token keyword">else</span>
  <span class="token builtin class-name">echo</span> <span class="token string">"Failed to start timer"</span>
  <span class="token builtin class-name">exit</span> <span class="token number">1</span>
<span class="token keyword">fi</span>

Capturing output

Capture a command's output to parse it. hw project list supports machine-readable JSON via --json and a -q/--jq filter, which is the most reliable way to extract fields:

bash 
<span class="token comment"># Capture the full project list as JSON</span>
<span class="token assign-left variable">PROJECTS</span><span class="token operator">=</span><span class="token variable"><span class="token variable">$(</span>hw project list <span class="token parameter variable">--json</span> id,name<span class="token variable">)</span></span>

<span class="token comment"># Extract a single field with the built-in jq filter</span>
<span class="token assign-left variable">FIRST_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">'.[0].id'</span><span class="token variable">)</span></span>

<span class="token comment"># Other commands print human-readable output you can grep</span>
hw timer status

In this section