Timebook CLI
Command-line client and MCP server for Timebook — track time, manage timers, and expose your Timebook account to AI agents (Claude, Codex, Cursor, …) over the Model Context Protocol.
Install
# one-off
npx @squidcode/timebook login
# globally
npm install -g @squidcode/timebook
timebook --helpRequires Node.js 18.17+.
Authenticate
timebook login opens your browser, you log into Timebook (or use an existing session) and pick a scope (which clients/projects this token can touch). The browser delivers the token back to a short-lived loopback HTTP listener, which the CLI then writes to a config file with 0600 permissions.
timebook loginThe token is stored at:
- macOS:
~/Library/Preferences/timebook/config.json - Linux:
~/.config/timebook/config.json - Windows:
%APPDATA%\timebook\Config\config.json
The token never leaves your machine after login. To revoke it server-side, visit https://usetimebook.com/settings/api-tokens.
Use it as a CLI
timebook whoami
timebook projects # list projects
timebook clients # list clients
timebook start -p "Acme website" -d "Wireframes"
timebook status # show running timer
timebook stop
# manual entries
timebook log -p "Acme website" -t 1h30m -d "Code review"
timebook log -p PROJ_ID --start 2026-05-04T09:00 --end 2026-05-04T10:30
timebook entries --project "Acme website" -n 10
# edit / delete (any combination of fields; unset ones stay as-is)
timebook entries edit ENTRY_ID -t 2h -d "code review + tests"
timebook entries edit ENTRY_ID --start 2026-05-04T09:00 --end 2026-05-04T11:00
timebook entries edit ENTRY_ID -d "" # clear description
timebook entries delete ENTRY_ID
