CLI Integrations

Wire the Heyweek CLI into the tools you already use to automate the work around your work.

Overview

The Heyweek CLI doesn't expose a separate API — integration happens by wrapping the same hw commands you run by hand inside scripts, CI/CD steps, and shell helpers. Anything you can run from a terminal, you can automate.

Key Features

• Scriptable — Drive hw commands from shell scripts and your own programs.
• CI/CD ready — Run CLI commands as steps in your pipelines.
• Shell & editor integration — Trigger commands from where you already work.
• Automated time entries — Start and stop timers programmatically around your tasks.
• Machine-readable output — Use --format json or --format tsv to feed data into other tools.

Scripts

Call CLI commands from shell scripts to chain Heyweek actions with the rest of your tooling. Combine project, client, timer, and log commands to mirror your real process:

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

<span class="token comment"># Start tracking a task, do the work, then stop</span>
hw timer start <span class="token parameter variable">-d</span> <span class="token string">"Nightly data import"</span>
./run-import.sh
hw timer stop

Build on the patterns in Scripting.

CI/CD pipelines

The CLI runs unattended as a step in your pipelines. Provide the auth token through the HEYWEEK_TOKEN environment variable (stored as a secret) so no interactive login is needed:

<span class="token comment"># In your CI job, with HEYWEEK_TOKEN supplied as a secret</span>
<span class="token builtin class-name">export</span> <span class="token assign-left variable">HEYWEEK_TOKEN</span><span class="token operator">=</span><span class="token string">"<span class="token variable">$CI_HEYWEEK_TOKEN</span>"</span>

hw timer start <span class="token parameter variable">-d</span> <span class="token string">"CI build: <span class="token variable">$BUILD_ID</span>"</span>
<span class="token function">make</span> build
hw timer stop

This is useful for logging activity or recording time around automated builds and deploys.

Shell & editor integration

• Bind common commands to your own shell aliases or functions so they're a keystroke away (for example alias hts='hw timer start').
• Hook timer commands into editor or terminal events to track work as you do it.
• Keep Heyweek in your flow rather than asking you to context-switch.

Automating time and reporting

Use machine-readable output to feed dashboards or summaries. Most list commands accept --format json or --format tsv:

<span class="token comment"># Pull recent logs as JSON for a custom report</span>
hw log list <span class="token parameter variable">--format</span> json <span class="token operator">></span> today-logs.json

<span class="token comment"># Export projects as TSV for a spreadsheet</span>
hw project list <span class="token parameter variable">--format</span> tsv <span class="token operator">></span> projects.tsv

Combine these with cron or your scheduler of choice to keep records flowing without manual upkeep.

Works with the rest of Heyweek

• Start from the CLI overview to learn the available commands.
• Lean on Scripting for reusable automation patterns.
• Package the result into repeatable Workflows.

Tips

• Store credentials securely in CI (as secrets) rather than hard-coding tokens into scripts.
• Start with one small automation, prove it works, then expand.