CLI

Clessira ships with a small terminal helper called clessira. Use it to start and stop tracking, log time after the fact, or query the current state — without bringing the app to the foreground.

Under the hood, the CLI talks to the running Mac app via the AppleScript interface. The app needs to be running (menu-bar icon visible).

Install

In the Mac app: Settings → Integrations → CLI → Install in PATH. Clessira drops the command into ~/.local/bin/clessira and shows in the status pane whether ~/.local/bin is already on your PATH. If not, the app hands you the matching export snippet for your shell — add it to ~/.zshrc (or ~/.bashrc).

Uninstall via the same pane using Deinstallieren (Uninstall).

After an app update, run Install in PATH again to bring the CLI back in sync with the app.

Commands

clessira start <activity> [--create-if-missing]
clessira stop
clessira log <activity> --duration <minutes|Xm|Xh|XhYm> [--note <text>] [--create-if-missing]
clessira today
clessira status
clessira help

start

Starts tracking for an existing activity:

clessira start "Refactor"

With --create-if-missing, Clessira creates the activity if it doesn’t exist:

clessira start "PROJ-123 Review" --create-if-missing

The name must match an active activity exactly — archived ones are ignored.

stop

Stops the running session:

clessira stop

If nothing is running, the call still succeeds (no-op).

log

Logs a time block after the fact. The duration can be expressed as minutes or in shorthand:

clessira log "Standup" --duration 15
clessira log "Deep Work" --duration 1h30m --note "API refactor"
clessira log "Pairing" --duration 2h --create-if-missing

Accepted duration formats: 30 (minutes), 45m, 2h, 1h30m. The entry ends now and starts that far in the past.

today

Prints the total time tracked today, in hours:

$ clessira today
3.75

The output is a decimal number — handy for shell pipelines.

status

Prints a compact status block:

$ clessira status
isTracking=true
currentActivity=Refactor
todayHours=3.75

Three key=value lines, ready for grep or awk.

Examples

Log a lunch break after the fact:

clessira log "Mittag" --duration 45m --create-if-missing

Show the active activity in your shell prompt:

clessira status | awk -F= '/currentActivity/ {print $2}'

Start tracking from a terminal multiplexer keybinding:

clessira start "Tickets" --create-if-missing && tmux display-message "tracking started"

Errors & exit codes

clessira exits with 0 on success and 1 on errors. Common causes:

• Activity '…' not found — activity is missing or archived. Use --create-if-missing.
• TrackingManager not available — the Mac app isn’t running. Launch it and retry.
• Clessira is locked: no valid license installed — missing or expired license. Check Settings → License.
• AppleScript permission — on the first call, macOS asks whether your terminal may control Clessira. Confirm with OK. If you accidentally denied it, re-enable under System Settings → Privacy & Security → Automation.

What the CLI does not do

• Rename, archive or delete activities — only the app can do that.
• Edit or delete entries — log only appends new ones.
• Open the tracking prompt programmatically — use the HTTP API (POST /branch-changed) for that.

For more control (e.g. searching activities, branch-change hooks), use the HTTP API or one of the SDKs.