timetracker-cli

A .NET 10 command-line tool for logging and managing time entries in 7pace Timetracker.

Installation

Requires the .NET 10 Runtime (the SDK is only needed to build from source).

dotnet tool install -g timetracker-cli

Update

dotnet tool update -g timetracker-cli

Uninstall

dotnet tool uninstall -g timetracker-cli

---

Prerequisites

• .NET 10 Runtime (the SDK is only needed to build from source)
• A 7pace Timetracker instance with a valid Bearer Token

Build from source

dotnet build Timetracker
dotnet publish Timetracker -c Release

First-time setup

Before using any command, run config to authenticate and cache your activity types locally:

timetracker config -u https://<company>.timehub.7pace.com -t <bearer-token>

---

Commands

• config
• activities
• add
• list
• summary
• interactive
• update
• copy
• delete
• import

---

config

Configure the connection to your Timetracker instance.

Option	Short	Required	Description
--url	-u	yes*	Base URL of your Timetracker instance
--token	-t	yes*	Bearer token for authentication
--border		no	Table border style for list output: minimal (default), square, or markdown
--show		no	Display current config (token masked)
--reset		no	Delete all local config and activity cache

*Required only on first-time setup.

Configuration updates are non-destructive: once configured, each option can be changed on its own and everything else is preserved. Only --url/--token trigger a re-authentication (and refresh of the activity cache).

# Initial setup
timetracker config -u https://acme.timehub.7pace.com -t eyJ...

# View current config
timetracker config --show

# Rotate just the token (URL and other settings are kept)
timetracker config -t eyJnew...

# Change the list table border (no network call, credentials untouched)
timetracker config --border square

# Remove all local config
timetracker config --reset

---

activities

List available activity types. Uses a local cache populated during config.

Option	Short	Required	Description
--sync		no	Refresh the activity type cache from the server before listing

# List cached activity types
timetracker activities

# Sync from server then list
timetracker activities --sync

---

add

Create a new time entry.

Option	Short	Required	Description
--date	-d	no	Date: YYYY/MM/DD, today, or yesterday (default: today)
--work-item	-w	yes*	Work Item ID
--length	-l	yes*	Duration in hours (e.g. 0.5, 1.5)
--type	-t	yes*	Activity type name (see activities)
--comment	-c	no	Comment for the entry
--hour	-h	no	Start time in HH:MM format (default: 09:00)
--interactive	-i	no	Prompt for each field instead of passing flags
--dry-run		no	Preview the entry locally without submitting

*Required in the flag-based flow; supplied through prompts when --interactive is used.

# Log 2 hours of development today (date defaults to today)
timetracker add -w 12345 -l 2 -t Development -c "Feature X"

# Log half an hour of a meeting starting at 14:00
timetracker add -d 2026/06/19 -w 12345 -l 0.5 -t Meeting -h 14:00

# Guided mode — prompts for date, hour, work item, duration, type, and comment
timetracker add --interactive

# Preview before submitting
timetracker add -d today -w 12345 -l 1 -t Development --dry-run

In --interactive mode, date and start hour default to today and 09:00, the activity type is picked from a list, and the comment is optional. The collected values still pass through the same validation as the flag-based flow.

---

list

List time entries for a period.

Option	Short	Required	Description
--from	-f	no	Start date (default: today)
--to	-t	no	End date (default: today)
--period	-p	no	Specific month in YYYY/MM format (e.g. 2026/06)
--work-item	-w	no	Filter by Work Item ID
--output	-o	no	Output format: json (batch-upload compatible) or csv
--today		no	Shortcut for today's entries
--yesterday		no	Shortcut for yesterday's entries
--week		no	Entries for the current week (Mon–Sun)
--last-week		no	Entries for the previous week (Mon–Sun)
--month		no	Entries for the current month
--last-month		no	Entries for the previous month
--ids		no	Show entry IDs in the last column, in place of comments

All period shortcuts (--today, --yesterday, --week, --last-week, --month, --last-month) and --period are mutually exclusive and cannot be combined with --from or --to.

# Today's entries
timetracker list --today

# Yesterday's entries
timetracker list --yesterday

# Current week
timetracker list --week

# Previous week
timetracker list --last-week

# Current month
timetracker list --month

# Previous month
timetracker list --last-month

# Specific date range
timetracker list -f 2026/06/01 -t 2026/06/30

# Specific month
timetracker list --period 2026/06

# Filter by work item and show IDs (for delete/update)
timetracker list --week --work-item 12345 --ids

# Export week as JSON for batch upload
timetracker list --week --output json > worklogs.json

# Export month as CSV
timetracker list --month --output csv > worklogs.csv

---

summary

Show a daily breakdown of logged hours for a period — one row per day with total hours and entry count. Useful for spotting days with missing or incomplete hours.

Accepts the same period options as list.

Option	Short	Required	Description
--from	-f	no	Start date (default: today)
--to	-t	no	End date (default: today)
--period	-p	no	Specific month in YYYY/MM format
--work-item	-w	no	Filter by Work Item ID
--output	-o	no	Output format: json or csv. Defaults to a table
--today		no	Today
--yesterday		no	Yesterday
--week		no	Current week (Mon–Sun)
--last-week		no	Previous week (Mon–Sun)
--month		no	Current month
--last-month		no	Previous month

# Daily totals for the current week
timetracker summary --week

# Export the monthly breakdown as CSV
timetracker summary --month --output csv > breakdown.csv

# Current month
timetracker summary --month

# Specific month
timetracker summary --period 2026/06

# A single work item across the month
timetracker summary --month --work-item 12345

---

interactive

Browse, create, copy, edit and delete time entries in an interactive terminal UI. Navigate with arrow keys and confirm actions via prompts. Defaults to today's entries.

Option	Short	Required	Description
--period	-p	no	Specific month in YYYY/MM format
--work-item	-w	no	Filter by Work Item ID
--today		no	Entries for today (default)
--yesterday		no	Entries for yesterday
--week		no	Entries for the current week
--last-week		no	Entries for the previous week
--month		no	Entries for the current month
--last-month		no	Entries for the previous month

# Browse today's entries
timetracker interactive

# Browse this week's entries
timetracker interactive --week

# Browse a specific month
timetracker interactive --period 2026/06

# Browse filtered by work item
timetracker interactive --week --work-item 12345

Flow:

• Select an entry → choose Edit, Copy, Delete, or Back → confirm/fill fields → returns to the list automatically.
• Edit → update any field; activity type change is optional (confirm prompt).
• Copy → pre-fills all fields from the original entry (date defaults to today); edit any field before saving as a new entry.
• Delete → confirmation prompt before removal.
• Select ── New entry ── → fill in date, start hour, work item, duration, activity type, and comment → entry is created and the list refreshes.
• Select ── Exit ── to quit.

---

update

Update one or more fields of an existing time entry. Only the fields provided are changed.

Option	Short	Required	Description
--id	-i	yes	ID of the entry to update
--date	-d	no	New date
--work-item	-w	no	New Work Item ID
--length	-l	no	New duration in hours
--type	-t	no	New activity type
--comment	-c	no	New comment
--hour	-h	no	New start time

# Fix the duration of an entry
timetracker update -i <id> -l 3

# Change the work item and comment
timetracker update -i <id> -w 99999 -c "Moved to correct item"

---

copy

Duplicate an existing entry to a target date (defaults to today). Preserves work item, duration, activity type, comment, and start time.

Option	Short	Required	Description
--id	-i	yes	ID of the entry to copy
--date	-d	no	Target date (default: today)

# Copy a recurring entry to today
timetracker copy -i <id>

# Copy to a specific date
timetracker copy -i <id> -d 2026/06/20

---

delete

Delete one or more time entries by ID.

Option	Short	Required	Description
--id	-i	yes	ID(s) to delete. Repeat the flag or separate with commas
--force		no	Skip the confirmation prompt

# Delete a single entry (with confirmation)
timetracker delete -i <id>

# Delete multiple entries
timetracker delete -i <id1> -i <id2> -i <id3>

# Delete multiple entries using comma separator
timetracker delete -i <id1>,<id2>,<id3>

# Skip confirmation
timetracker delete -i <id1> -i <id2> --force

---

import

Import multiple time entries from a JSON file. The file must be an array of worklog objects, compatible with the output of list --output json.

Option	Short	Required	Description
--file	-f	yes	Path to the JSON file
--dry-run		no	Preview entries locally without submitting

# Preview what would be imported
timetracker import --file worklogs.json --dry-run

# Import
timetracker import --file worklogs.json

---

Common workflows

Manage entries interactively

For day-to-day work, interactive is the fastest path — create, copy, edit, and delete without memorizing flags. It defaults to today's entries.

# Drive the whole day from a single terminal UI
timetracker interactive

# Review and fix a past week
timetracker interactive --last-week

Log a full day

# Several entries on the same day, across different work items
timetracker add -d today -w 12345 -l 2 -t Development -c "Feature X"
timetracker add -d today -w 12345 -l 1.5 -t Development -c "Code review"
timetracker add -d today -w 67890 -l 0.5 -t Meeting -h 14:00 -c "Daily"

# Review what was logged
timetracker list --today

Find and delete an entry

# List today's entries with IDs
timetracker list --today --ids

# Delete the target entry
timetracker delete -i <id>

Fix an entry logged to the wrong work item

timetracker list --today --ids
timetracker update -i <id> -w <correct-work-item>

Copy a recurring daily entry

# Find the original entry ID once
timetracker list -f 2026/06/01 -t 2026/06/01 --ids

# Copy it every day
timetracker copy -i <id>

Export, edit, and re-import a week

# Export
timetracker list --week --output json > worklogs.json

# Edit worklogs.json as needed, then preview
timetracker import --file worklogs.json --dry-run

# Import
timetracker import --file worklogs.json

Replicate last week

For a fixed weekly routine, export the previous week, shift the dates, and re-import.

# Export last week
timetracker list --last-week --output json > lastweek.json

# Edit lastweek.json: bump each "date" forward by 7 days, then preview
timetracker import --file lastweek.json --dry-run

# Import
timetracker import --file lastweek.json

Check for missing entries

Spot days with incomplete or no hours before the month closes.

# Daily totals for the current week — gaps stand out
timetracker summary --week

# Same for a specific month
timetracker summary --period 2026/06

Monthly summary

# Current month
timetracker summary --month

# Specific month
timetracker summary --period 2026/06

---

Security

Credential storage

The bearer token and user info are stored locally in a config file. The location and protection method depend on the OS:

OS	Location	Protection
Windows	%LOCALAPPDATA%\Timetracker.Console\config.json	Token encrypted with DPAPI (user-scoped)
Linux / macOS	~/.config/Timetracker.Console/config.json	File permissions set to 600 (owner read/write only)

On Windows, the encrypted token can only be decrypted by the same OS user account that ran config. On Linux/macOS, the file is not encrypted but is restricted to the owner.

HTTPS enforcement

The --url option only accepts https:// URLs. Plain HTTP is rejected to prevent the bearer token from being transmitted over an unencrypted connection.

---

Troubleshooting

401 Unauthorized on any command

The bearer token has expired or is invalid. Run config again with a new token:

timetracker config -u https://<company>.timehub.7pace.com -t <new-token>

Activity type 'X' not found

The local activity cache is out of sync with the server. Refresh it:

timetracker activities --sync

config.json does not exist

The tool has not been configured yet. Run the first-time setup:

timetracker config -u https://<company>.timehub.7pace.com -t <bearer-token>

The provided URL is invalid or does not use HTTPS

The URL must start with https://. Example:

# Wrong
timetracker config -u http://acme.timehub.7pace.com -t <token>

# Correct
timetracker config -u https://acme.timehub.7pace.com -t <token>