@timesheet/cli

Command-line interface for timesheet.io time tracking.

Installation

npm install -g @timesheet/cli

Authentication

OAuth 2.1 (Recommended)

The CLI supports OAuth 2.1 with PKCE for secure authentication:

timesheet auth login

This opens a browser window for authentication. The CLI automatically registers itself using Dynamic Client Registration (RFC 7591).

API Key

For automation and CI/CD environments:

# Set via environment variable
export TIMESHEET_API_KEY=ts_your.apikey

# Or configure in CLI
timesheet auth apikey --set ts_your.apikey

Check authentication status:

timesheet auth status

Usage

Timer Commands

# Start timer for a project
timesheet timer start <project-id>

# Check timer status
timesheet timer status

# Pause/resume timer
timesheet timer pause
timesheet timer resume

# Stop timer (creates task)
timesheet timer stop

Project Commands

# List projects
timesheet projects list

# Create a project
timesheet projects create "My Project"

# Show project details
timesheet projects show <id>

# Update/delete
timesheet projects update <id> --title "New Name"
timesheet projects delete <id>

Task Commands

# List recent tasks
timesheet tasks list

# List today's tasks
timesheet tasks list --today

# Create a task manually
timesheet tasks create -p <project-id> -s "2024-01-15 09:00" -e "2024-01-15 17:00"

# Show/update/delete
timesheet tasks show <id>
timesheet tasks update <id> --billable
timesheet tasks delete <id>

Teams & Tags

# List teams
timesheet teams list

# List/create/delete tags
timesheet tags list
timesheet tags create "Urgent" --color 1
timesheet tags delete <id>

Reports

# Time summary
timesheet reports summary --this-month

# Export data
timesheet reports export -f xlsx -s 2024-01-01 -e 2024-01-31

Profile & Settings

# Show profile
timesheet profile show

# Show settings
timesheet profile settings

Configuration

# Show config
timesheet config show

# Set a value
timesheet config set defaultProjectId <id>

# Reset to defaults
timesheet config reset

Output Formats

The CLI supports three output formats:

Human-Readable (Default)

Formatted tables with colors, shown when running in a terminal:

Timer Status

  Status:    ● Running
  Project:   Website Redesign
  Duration:  2h 34m
  Started:   Today, 09:15 AM

Pipe-Friendly

Tab-separated values, automatically used when piping output:

timesheet projects list | cut -f1,2

JSON

Machine-readable JSON output with --json flag:

timesheet timer status --json

Global Options

Option	Description
--json	Output as JSON
--no-color	Disable colors
--api-key <key>	Use API key for this command
--verbose	Verbose output
-q, --quiet	Suppress non-essential output
-h, --help	Show help
-v, --version	Show version

Configuration

Configuration is stored in ~/.timesheet-cli/:

Key	Description	Default
apiUrl	API base URL	https://api.timesheet.io
colors	Enable colors	true
dateFormat	Date format	yyyy-MM-dd
timeFormat	Time format	HH:mm
defaultProjectId	Default project for timer	-
defaultTeamId	Default team for new projects	-
confirmDeletes	Confirm before deleting	true
paginationLimit	Default page size	20

Environment variables override config file settings. Use TIMESHEET_ prefix:

export TIMESHEET_API_KEY=your-key
export TIMESHEET_COLORS=false

Exit Codes

Code	Description
0	Success
1	General error
2	Usage error (invalid arguments)
3	Authentication error
4	API error
5	Rate limit exceeded
6	Network error

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js --help

# Development mode (watch)
npm run dev

License

MIT