# The sumhour command line

Time tracking without leaving the terminal, built on the REST API. It needs Node 24 and nothing else.

## Sign in

```bash
sumhour login
```

The terminal shows a code like `WDJB-MJHT` and opens https://app.sumhour.com/device. Check the code matches, pick the workspace and what the CLI may do, and approve. The CLI keeps a token that expires in 180 days and shows up under **API tokens**; `sumhour logout` revokes it.

For CI and agents, skip the browser: set `SUMHOUR_TOKEN` (and `SUMHOUR_URL` for a self-hosted server).

## Everyday use

```bash
sumhour start acme portal -m "Kickoff"   # words match client, project or code
sumhour stop
sumhour log 1:30 AH-2 -m "Design review" -t design
sumhour entries --today
sumhour week && sumhour submit
```

## Account

```
sumhour login [--url URL] [--token sh_pat_…]   Sign in through the browser (or save a token)
sumhour logout                                 Revoke this device's token and forget it
sumhour whoami                                 Who you are signed in as, and where
```

## Time

```
sumhour status                                 Running timer and today's total
sumhour start [project] [-t task] [-m notes]   Start a timer (no project: resume today's last entry)
sumhour stop                                   Stop the running timer
sumhour log <duration> <project> [-m] [-t] [-d date] [--non-billable]   Log finished time (1:30, 1.5h, 90m)
sumhour entries [--today|--yesterday|--from D --to D] [--all] [-p project]   List time (default this week)
sumhour edit <id> [--duration] [-m] [-d] [-p] [--billable|--non-billable]   Change an entry
sumhour rm <id> [--yes]                        Delete an entry
sumhour week [date]                            A week's timesheet and status
sumhour submit [date]                          Submit the week for approval
```

## Workspace

```
sumhour projects [search]                      Projects you can log to, with codes and tasks
sumhour clients                                Active clients
sumhour people                                 Everyone in the workspace
```

## Money

```
sumhour expense <amount> <project> [-m] [-c category] [--reimbursable]   Add an expense
sumhour invoices [--status sent]               Invoices (accountants and admins)
sumhour report [time|profitability|utilization|invoicing|uninvoiced] [--preset this_month] [--group project]
sumhour approvals                              Weeks waiting for review (managers)
```

## Other

```
sumhour api <METHOD> <path> [--data JSON|@file]   Any /api/v1 call, JSON out
```

## For scripts and agents

- `--json` on every command; lists come back as plain arrays.
- `--dry-run` on every write prints the exact request and sends nothing.
- Deleting asks first at a terminal and needs `--yes` elsewhere.
- A project name that matches several projects is an error that lists them, never a guess.
- `sumhour api GET /projects` reaches any [API endpoint](/developers/api).

| Exit code | Meaning |
|---|---|
| 0 | Done |
| 2 | Usage problem, or an ambiguous project |
| 3 | Not signed in, token revoked or expired |
| 4 | Refused by the server (validation, permissions, locked time) |
| 5 | Server or network failure |

## Install

The npm package ships with the public launch. Until then, from a clone of the repository: `pnpm sumhour <command>`.