Command-line interface for timesheet.io time tracking
npm install @timesheet/cliCommand-line interface for timesheet.io time tracking.
``bash`
npm install -g @timesheet/cli
The CLI supports OAuth 2.1 with PKCE for secure authentication:
`bash`
timesheet auth login
This opens a browser window for authentication. The CLI automatically registers itself using Dynamic Client Registration (RFC 7591).
For automation and CI/CD environments:
`bashSet via environment variable
export TIMESHEET_API_KEY=ts_your.apikey
Check authentication status:
`bash
timesheet auth status
`Usage
$3
`bash
Start timer for a project
timesheet timer start Check timer status
timesheet timer statusPause/resume timer
timesheet timer pause
timesheet timer resumeStop timer (creates task)
timesheet timer stop
`$3
`bash
List projects
timesheet projects listCreate a project
timesheet projects create "My Project"Show project details
timesheet projects show Update/delete
timesheet projects update --title "New Name"
timesheet projects delete
`$3
`bash
List recent tasks
timesheet tasks listList today's tasks
timesheet tasks list --todayCreate a task manually
timesheet tasks create -p -s "2024-01-15 09:00" -e "2024-01-15 17:00"Show/update/delete
timesheet tasks show
timesheet tasks update --billable
timesheet tasks delete
`$3
`bash
List teams
timesheet teams listList/create/delete tags
timesheet tags list
timesheet tags create "Urgent" --color 1
timesheet tags delete
`$3
`bash
Time summary
timesheet reports summary --this-monthExport data
timesheet reports export -f xlsx -s 2024-01-01 -e 2024-01-31
`$3
`bash
Show profile
timesheet profile showShow settings
timesheet profile settings
`$3
`bash
Show config
timesheet config showSet a value
timesheet config set defaultProjectId Reset to defaults
timesheet config reset
`Output Formats
The CLI supports three output formats:
$3
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
`$3
Tab-separated values, automatically used when piping output:
`bash
timesheet projects list | cut -f1,2
`$3
Machine-readable JSON output with
--json flag:`bash
timesheet timer status --json
`Global Options
| Option | Description |
|--------|-------------|
|
--json | Output as JSON |
| --no-color | Disable colors |
| --api-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:`bash
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
`bash
Install dependencies
npm installBuild
npm run buildRun locally
node dist/index.js --helpDevelopment mode (watch)
npm run dev
``MIT