Snag help › Snag for the desktop
Command line
snag <command> [options]Commands
| Command | Does | Needs the daemon |
|---|---|---|
run | the daemon: tray icon, timer window, idle detection. One per session | - |
start | start the timer on the task last worked on | yes |
stop | stop the running timer | yes |
toggle | stop if running, start if not | yes |
show | raise and focus the timer window | yes |
status | print what the timer is doing | yes |
reload | re-read the stored token and resume syncing (login does this itself) | yes |
capture | open the capture box | no (opens its own box without one) |
login | store a personal access token after checking it | no |
logout | remove the stored token | no |
whoami | the account, abilities, expiry and store of the stored token | no |
doctor | what this machine can do; see Troubleshooting | no |
tasks | the task picker's list as JSON | no |
retro | time entries from git history; see Time from git history | no |
observed | what observation has recorded; see Observation | no |
forget | delete what observation recorded | no |
-h, --help | usage | no |
-V, --version | the version, one line | no |
Commands that need the daemon talk to it over a socket. With no daemon running they say so and exit 1; they never start one.
run
| Flag | Means |
|---|---|
--db PATH | the SQLite file to use |
--memory | in-memory database; nothing is kept, nothing syncs |
--tray | start with no window shown |
--label MODE | off, duration or duration+project |
--instance URL | the server to sync with |
--task P:T:PROJECT:TASK | a task to start on when the database has no history: project id, task id, project name, task name |
--seconds N | shut down cleanly after N seconds |
--idle-threshold N | seconds with no input before an idle span opens |
--idle-grace N | seconds a prompt waits before it becomes unanswered |
--idle-advisory | record idle spans, never prompt |
--no-idle | turn idle detection off |
capture
| Flag | Means |
|---|---|
--kind task or --kind note | open as this kind |
--note | same as --kind note |
login
| Flag | Means |
|---|---|
--instance URL | use this server and skip the prompt |
--no-browser | print the token page rather than opening it |
With standard input not a terminal, login reads the token from it and prompts for nothing.
doctor, observed
--json prints the same facts as JSON.
forget
--all also deletes derivations, and the sightings they were built from.
tasks
Prints one JSON object:
{
"source": {"kind": "cached", "as_of": "2026-10-16T09:00:00Z"},
"tasks": [ ... ]
}source.kind is cached (the fetched list), stale (fetched, but the last refresh failed; why says why) or local (only tasks this machine has logged against).
Exit codes
| Code | Means |
|---|---|
| 0 | done |
| 1 | refused, no daemon to ask, or (for doctor) something needs attention |
| 2 | the command line was wrong |
| 3 | run found another daemon already running |
Next: Where data goes