CLI Best Practices

Practical habits that keep the Heyweek CLI fast, safe, and reliable in daily use.

Overview

The CLI rewards a little discipline. A clean configuration, consistent naming, and a handful of shell aliases turn ad-hoc commands into a workflow you can trust — and one that's safe to automate.

Key Features

• Auth hygiene — Keep authentication current and let the CLI store tokens securely.
• Consistent naming — Use predictable names for projects and clients.
• Safe scripting — Write automation that fails loudly rather than silently.
• Useful shell aliases — Wrap the commands you run constantly into short shortcuts.
• Accurate timers — Build habits that keep tracked time honest.

Configuration & auth hygiene

• Authenticate once with hw auth login; the CLI stores your token in your operating system's keyring rather than in plain files.
• When a session expires, refresh it with hw auth renew instead of working around it.
• Check the active context with hw workspace info when switching machines or workspaces, so you're always acting on the right account.

Consistent project & client naming

• Agree on a naming convention for projects and clients, and stick to it across the team.
• Predictable names make commands easy to recall and scripts easy to write.
• Consistency here pays off everywhere downstream — in lists, filters, and reports.

Scripting safely

• Have scripts check command results and stop on failure rather than pushing through errors.
• Test against a non-critical project before automating against live work.
• See Scripting for patterns to build on.

Keeping timers accurate

• Start a timer when you begin and stop it when you finish — short, honest intervals beat guesswork.
• Check hw timer status if you're unsure whether a timer is running before starting another.
• Add a clear description with -d (for example hw timer start -d "Bug fix") so the entry is meaningful later.

Works with the rest of Heyweek

• Get oriented with the CLI overview.
• Turn repeated steps into repeatable Workflows.

Tips

• Define your own shell aliases for the commands you run most (for example alias hts='hw timer start') so the right thing is also the easy thing.
• Make stopping a forgotten timer part of your end-of-day routine.