Autumn CLI

Command-line interface for AutumnWeb — time tracking and project management from your terminal.

Installation

Using pip

cd cli
pip install -e .

Or from the AutumnWeb root directory:

pip install -e ./cli

Using uv

cd cli
uv pip install -e .

Or from the AutumnWeb root directory:

uv pip install -e ./cli

Running tests

pytest is tracked in the CLI's dev dependency group.

cd cli
uv run --group dev python -m pytest

Getting Started

1) Authenticate

Autumn CLI supports two authentication flows:

Option A: API token (existing)

autumn auth setup

You’ll be prompted for:

• API Key: Your AutumnWeb API token
• Base URL: Your AutumnWeb instance URL (default: http://localhost:8000)

Option B: Username/email + password (new)

This will request a token from the server and save it to your config file:

autumn auth login

Options:

• --username (or email)
• --password (will prompt if omitted)
• --base-url

2) Verify configuration

autumn auth status
autumn auth verify
autumn auth accounts

If you log into multiple accounts against the same AutumnWeb instance, you can switch between them quickly:

autumn auth switch alice

3) Say hi

Running autumn with no subcommands prints a short, dynamic greeting (time-of-day / moon phase / seasonal vibes).

autumn

Command Reference

Area	Command	What it does	Common options
Timers	autumn start <project>	Start a timer (with optional server-side auto-stop)	-s, -n, --for, --remind-in, --pick
	autumn status	Show active timers and auto-stop timing	-p, -i
	autumn stop	Stop timer	-p, -i, -n
	autumn restart	Reset start time to now	-p, -i
	autumn resume	Resume last project	--stop-current
Logs	autumn log	List sessions (saved)	-P month, -p, -x, -t, -c, --pick
	autumn log search	Advanced search	--note-snippet, --start-date, -x
	autumn track	Manually log a session	--start, --end, -n
Projects	autumn projects	List projects by status	-S active, -c, -x, -t, -d, --search
	autumn project	Show or edit a project's metadata	<name>, edit <name>
	autumn subprojects	List subprojects for a project	<project>, -d, --search
	autumn new	Create project or subproject	-s, -d, --context, --tags, --pick
	autumn mark	Change project status	<project> <status>, --pick
	autumn rename	Rename project or subproject	<old> <new>, -p for subprojects
	autumn totals	Show project time breakdown	<project>, --start-date, --end-date
	autumn merge	Merge two projects	<p1> <p2> --into <name>, -y
	autumn merge-subs	Merge two subprojects	<project> <s1> <s2> --into, -y
	autumn delete-project	Delete a project	<project>, -y, --pick
	autumn delete-sub	Delete a subproject	<project> <sub>, -y, --pick
Data	autumn export	Export sessions/projects JSON	-o, -d, -p, --stdout
	autumn import <file>	Import an export JSON or compressed export	--force, --merge, --tolerance, -y
	autumn audit	Recompute project totals	--dry-run
Reminders	autumn remind	Set ad-hoc reminders	at, every, in, session
	autumn reminders	Manage background workers	list, stop
Charts	autumn chart	Render charts	--type, -P, --color-by-project
Config	autumn config	Edit settings	show, set, open
Auth	autumn auth accounts	List saved accounts	—
	autumn auth switch <account>	Switch active account	—
	autumn alias	Manage aliases	add, list, remove
Metadata	autumn context	List and manage contexts	list, new, rename, edit, delete
	autumn tag	List and manage tags	list, new, rename, edit, delete
Commitments	autumn commitments (cmt)	Track recurring goals	list, show, new, edit, delete
Meta	autumn meta refresh	Clear cached metadata	—

Usage

Timer & Pomodoro Commands

Start a basic timer:

autumn start "AutumnWeb" --note "Implementing reminders"

Pomodoro / Timed Sessions: You can set a server-side auto-stop duration and various reminders when starting:

autumn start "Deep Work" --for 25m --remind-in 20m --remind-message "5 minutes left!"

--for sends the duration to AutumnWeb, so the timer stops even if this machine sleeps or the local CLI worker exits. autumn start, autumn restart, and autumn status show when an active timer auto-stops (and how long remains). The local worker only handles the desktop notification; it does not own the stop itself.

Periodic reminders (runs in background):

autumn start "Coding" --remind-every 1h --remind-message "Stand up and stretch!"

Reminders (Ad-hoc)

Set reminders independent of timers:

# Relative time
autumn remind in 15m --message "Check the oven"

# Absolute time
autumn remind at 5pm --message "Team Meeting"

# Periodic
autumn remind every 30m --message "Drink water"

# Attach to an existing session
autumn remind session 123 --every 20m --message "Review progress"

Managing Workers: Reminders run as background processes.

autumn reminders list       # See what's running
autumn reminders stop --all # Stop everything

Sessions & Logs

View activity for the current week (default):

autumn log

Filter by period, project, or tags:

autumn log -P month -p "AutumnWeb" -t "Feature"

Exclude one or more projects from logs:

autumn log -P month -x "Admin" -x "Meta"
autumn log search --start-date 2026-01-01 --exclude "Admin"

Note: Short flag -P is for Period, and -p is for Project.

Projects & Subprojects

List all projects:

autumn projects
autumn p            # Alias
autumn projects -d  # Show descriptions
autumn projects -x "Admin" -x "Meta"  # Exclude projects

List subprojects for a specific project:

autumn subprojects "AutumnWeb"
autumn subs "AutumnWeb"        # Alias

Create a new project or subproject:

autumn new "My Project" -d "Project description"
autumn new "My Project" --context Work --tags "Important,Client"
autumn new "My Project" -s "Backend" -d "Backend services"  # Create subproject
autumn new --pick -s "New Feature"  # Interactive project selection

Project Management

Change project status:

autumn mark "Old Project" complete
autumn mark "Side Project" paused
autumn mark --pick  # Interactive selection

Valid statuses: active, paused, complete, archived

Rename projects or subprojects:

autumn rename "Old Name" "New Name"
autumn rename "OldSub" "NewSub" -p "Parent Project"  # Rename subproject

View project time totals:

autumn totals "My Project"
autumn totals "My Project" --start-date 2026-01-01

View single project details:

autumn project "My Project"
autumn project --pick  # Interactive selection

Shows: status, total time, session count, average session duration, context, tags, and subprojects.

Edit project metadata:

autumn project edit "My Project" --description "New description" --context Work
autumn project edit "My Project" --clear-context
autumn project edit "My Project" --tags "Important,Client"  # Replace all tags
autumn project edit "My Project" --add-tag Urgent --remove-tag Client

Use either --tags to replace the complete tag list, or --add-tag / --remove-tag for incremental changes. --context and --clear-context cannot be combined.

Search projects and subprojects:

autumn projects --search "web"              # Search by name
autumn projects --search "api" -S all       # Search across all statuses
autumn projects --search "api" -x "Admin"   # Search while excluding projects
autumn subprojects "My Project" --search "frontend"

Merge projects:

autumn merge "Project A" "Project B" --into "Combined Project"
autumn merge --pick --into "Merged"  # Interactive selection

All sessions and subprojects from both projects are moved to the new project. The original projects are deleted.

Merge subprojects:

autumn merge-subs "My Project" "Frontend" "UI" --into "Frontend UI"
autumn merge-subs --pick --into "Merged Sub"

Delete projects or subprojects:

autumn delete-project "Old Project"      # Prompts for confirmation
autumn delete-project "Old Project" -y   # Skip confirmation
autumn delete-sub "Project" "Subproject"

Data Export & Maintenance

Export data to JSON:

By default, exports save to ~/Downloads with a timestamped filename.

autumn export                              # Export to ~/Downloads/autumn_export_20260129_143052.json
autumn export -p "My Project"              # Filter by project
autumn export -o backup.json               # Export to specific file
autumn export -d ~/backups                 # Export to custom directory
autumn export --stdout                     # Print to terminal (for piping)
autumn export --stdout | jq .sessions      # Pipe to jq
autumn export --compress                   # Compressed format

Import an export:

autumn import backup.json
autumn import autumn_export_compressed.txt --merge --tolerance 5 -y
autumn import legacy_export.json --autumn-format --context Work
autumn import replacement.json --force

Imports are performed by the server. Use --merge to merge into existing projects, or --force to delete same-named projects first; the two options are mutually exclusive. --context imports into that context (creating it if needed), and --autumn-format marks a legacy Autumn CLI export.

Configure a custom default directory:

autumn config set export.default_dir "~/backups"

Audit/recompute totals:

autumn audit
autumn audit --dry-run

This recalculates all project and subproject totals from session data. Useful after imports or if totals seem incorrect.

--dry-run previews what would change without saving anything. When the backend reports changed rows, the CLI prints the affected projects and subprojects with before -> after totals and the delta.

Interactive Selection

Many commands support --pick for interactive fuzzy-search selection:

autumn start --pick           # Pick project interactively
autumn log --pick             # Pick project/context/tags
autumn mark --pick            # Pick project to mark
autumn totals --pick          # Pick project for totals

The picker shows recent projects first and supports typing to filter the list.

Charts & Visualization

Autumn supports various chart types: pie, bar, scatter, calendar, wordcloud, heatmap.

# Calendar heatmap colored by project
autumn chart --type calendar --color-by-project

# Weekly bar chart for a specific context
autumn chart --type bar -P week --context Work

Contexts & Tags

Contexts and tags can be listed, created, renamed, edited, and deleted:

autumn context list -d
autumn context new Work --description "Client and office work"
autumn context rename Work "Client Work"
autumn context edit "Client Work" --description "Client-facing work"
autumn context delete "Client Work" -y

autumn tag list --color
autumn tag new Urgent --color red
autumn tag rename Urgent Priority
autumn tag edit Priority --color orange
autumn tag delete Priority -y

Pass an empty string to context edit --description or tag edit --color to clear that field. Deleting a context removes it from its projects but retains the projects and their other data.

Commitments

Commitments track recurring time or session goals for a project, subproject, context, or tag. autumn commitments (or autumn cmt) lists active commitments with progress, status, and balance.

autumn commitments --all --streak
autumn commitments show 12
autumn commitments new "AutumnWeb" --target-value 5h --period weekly
autumn cmt new "AutumnWeb/Backend" --type subproject --target-value 10 --commitment-type sessions --period monthly
autumn commitments new Work --type context --target-value 8h --include "Client Project"
autumn commitments edit 12 --target-value 6h --no-banking --max-balance 2h
autumn commitments delete 12

Time commitments accept duration values such as 5h for --target-value, --min-balance, and --max-balance; session commitments use whole session counts. --include and --exclude apply only to context or tag commitments. Use --json for raw list output, and --start-date to set a commitment's YYYY-MM-DD start date.

Configuration

Settings are stored in ~/.autumn/config.yaml. You can edit this file directly or use the CLI:

autumn config show    # View current config
autumn config open    # Open config file in default editor

Common Knobs:

• tls.insecure: true - Disable TLS verification (for local dev)
• greeting_activity_weight: 0.5 - How often to show activity in greetings (0-1)
• notify.log_file: "~/.autumn/notify.log" - Enable notification debug logging
• wake_retry: true - Automatically wake and retry a sleeping hosted server
• wake_timeout_seconds: 120 - Maximum seconds to wait for the server to become healthy

When a hosted instance such as a Render free-tier service is asleep, commands print a waking-up notice, poll /healthz/ with backoff, then retry automatically. Set wake_retry: false to fail fast, or override either setting for one environment with AUTUMN_WAKE_RETRY and AUTUMN_WAKE_TIMEOUT_SECONDS.

Aliases

Define short names for projects, contexts, tags, or subprojects using the alias command:

Add aliases:

autumn alias add project cli "Autumn CLI"
autumn alias add context w Work
autumn alias add tag imp Important
autumn alias add subproject fe Frontend -p "Autumn CLI"  # Scoped to project

# Interactive mode
autumn alias add project myalias --pick

List aliases:

autumn alias list                # Show all aliases
autumn alias list --type project # Filter by type
autumn alias list --json         # JSON output

Remove aliases:

autumn alias remove project cli
autumn alias remove subproject fe -p "Autumn CLI"

Use aliases in commands:

autumn start cli           # Resolves to "Autumn CLI"
autumn log -c w            # Resolves to "Work" context
autumn start cli -s fe     # Subproject alias resolves within project scope

Subproject aliases are project-scoped — the alias fe can map to different subprojects in different projects.

Features

• ✅ Full Timer Lifecycle: Start, stop, restart, resume, and delete.
• ✅ Pomodoro Support: Auto-stop timers and timed reminders.
• ✅ Project Management: Create, rename, mark status, merge, and delete projects/subprojects.
• ✅ Search & Discovery: Search projects and subprojects by name, view detailed project info.
• ✅ Interactive Pickers: Fuzzy-search selection with --pick flag.
• ✅ Data Export: Export sessions and projects to JSON with filtering.
• ✅ Background Reminders: NLP-powered reminders (at, every, in).
• ✅ Rich Visualization: Beautiful Matplotlib/Seaborn charts.
• ✅ Metadata Aware: Context and Tag filtering across all commands.
• ✅ Cross-Platform Notifications: Native toasts on Windows, macOS, and Linux.
• ✅ Smart Greetings: Dynamic, personalized messages based on time and activity.
• ✅ Case-Insensitive Input: Project/subproject names resolve regardless of case.
• ✅ Powerful Aliases: Dedicated alias commands with project-scoped subproject aliases.

Troubleshooting

• No notifications? Check autumn reminders list to see if the daemon is running. On macOS, Autumn uses terminal-notifier; if it is missing, the CLI will explicitly try brew install terminal-notifier on first use.
• SSL Errors? If using a self-signed cert, set autumn config set tls.insecure true.
• Outdated Data? Run autumn meta refresh to sync projects, tags, and contexts.
• Incorrect Totals? Run autumn audit to recompute all project/subproject totals from session data.