Punch CLI

Punch is a command-line tool for tracking tasks, generating reports, exporting timecards, and submitting them to Salesforce.
It uses Typer for its CLI, supports configuration management, and provides interactive and scriptable workflows.

Installation

pip install punch
# or if using poetry
poetry install

or

snap install punch

Usage

Main Commands

• punch start [-t HH:MM]
  Mark the start of your day. Optionally specify the start time.

• punch add [-t HH:MM] <category> : <task> [: <notes>]
  Add a new task entry. You can specify the time with -t.

• punch report [-d DAY | -f FROM -t TO]
  Print a report for a single day (-d) or a date range (-f/-t). Dates accept natural language (e.g. yesterday, 2025-01-01).

• punch export [options]
  Export timecards to CSV or JSON. Supports the same date options as report.

• punch login
  Log in to Salesforce and store your session locally.

• punch submit [options]
  Submit timecards to Salesforce. Supports dry-run, interactive/headed mode, and sleep between actions.

• punch config <subcommand>
  Manage configuration. Subcommands:

  • show — Show the current configuration.
  • edit — Edit the config file in $EDITOR.
  • path — Show the config file path.
  • set <option> <value> — Set a config value.
  • get <option> — Get a config value.
  • wizard — Run the interactive config wizard.

• punch help [COMMAND ...]
  Show help for the app or any subcommand.

• punch whats-new
  Show the changelog for the current version.

Excluding Tasks from Reports

You can mark tasks that should not be counted as work tasks (e.g., lunch breaks, personal time) by appending ** to the task name:

punch add "lunch**"
punch add "break**"

Tasks ending with ** will be excluded from reports and timecard calculations.

Interactive Mode

Running punch with no arguments launches an interactive prompt for selecting categories and tasks.

Date Handling

• Dates can be specified as natural language (yesterday, today, last monday) or as YYYY-MM-DD.
• For ranges, use -f/--from and -t/--to.
• -d/--day sets both start and end to the same day.

Configuration

Configuration is stored in a YAML file (see punch config path).
You can edit it directly, use punch config set/get, or run punch config wizard for guided setup.

Completion

Bash and Zsh completion scripts are provided in the repo (punch-completion.bash, zsh-completion).
Source them in your shell for tab completion of commands and options.

Examples

punch start -t 09:00
punch add c : "Implement feature X" : "Initial commit"
punch report -d yesterday
punch export --format csv -f 2025-01-01 -t 2025-01-31 -o jan.csv
punch config show
punch config set timecards_url https://example.com/timecards
punch submit -n -f 2025-01-01 -t 2025-01-31

Weekly Editor

By running:

punch weeklyeditor

The weekly editor provides an interactive Terminal User Interface (TUI) to view and manage your time cards for an entire week at a glance. It automatically calculates your daily and weekly totals and syncs directly with your underlying tasks.txt file.

Keyboard Controls

Navigation and editing are entirely keyboard-driven for speed and efficiency:

• ← / → (Left/Right Arrows): Move focus between different days of the week. Pressing Left on Sunday or Right on Saturday will automatically shift the view to the previous or next week.
• ↑ / ↓ (Up/Down Arrows): Navigate between individual time cards within a selected day, or navigate through lists inside the entry modal.
• Enter: Select/Edit the currently focused time card.
• a: Add a new task to the currently selected day.
• e: Edit the currently focused time card.
• d: Delete the currently focused time card (prompts for confirmation).
• q: Quit the weekly editor.

Smart Task Entry

When adding (a) or editing (e) a task, a modal will appear with several smart features:

• Categories: Your categories are automatically loaded from ~/.config/punch/punch.yaml. You can navigate this list using your Up/Down arrow keys.
• Duration: Time is entered simply as total minutes (e.g., 60). The editor handles the math behind the scenes, automatically sequencing the start and end timestamps for your tasks in the storage file (assuming a standard 08:30 AM start time).
• Smart Suggestions: As you highlight different categories, the "Suggestions" list will automatically populate with descriptions you have previously used for that specific category. You can arrow down to a suggestion and press Enter to instantly fill the description field.

Auto-Saving & Workflow

You do not need to manually save your week. Every time you add, edit, or delete a task, the editor automatically recalculates the timeline and safely rewrites the changes to ~/.local/share/punch/tasks.txt, preserving your history for dates outside the current view.

Note: The weekly editor only modifies your local tasks.txt file. After you are finished editing your tasks for the week, the regular punch submit commands still need to be issued to officially log your time.

Development

• All commands are implemented using Typer.
• Tests are in the tests/ directory and cover both core logic and CLI usage.
• See punch/cli.py for the main entrypoint.

License

MIT

---

For more details, see the CHANGELOG or run punch whats-new.