momentium-cli

v0.4.0

Published

2 months ago

Momentium CLI — manage your projects, tasks, calendar events, and habits from the terminal

0High
0Medium
0Low

crcatala

momentium cli productivity tasks projects calendar events habits todo task-manager terminal

Momentium CLI

A command-line interface for Momentium — manage your projects, tasks, and calendar events from the terminal.

Installation

npm install -g momentium-cli

Or run directly with npx:

npx momentium-cli --help

Requires Node.js 22.21.0–22.x or 24.0.0+.

Quick Start

# 1. Set your API key (get one from Momentium → Settings → API Keys)
momentium auth set-token

# 2. Verify authentication
momentium me

# 3. Start using it
momentium projects list --month 2026-02
momentium tasks list --project a1b2c3d4
momentium events list --today

Commands

Authentication

momentium auth status                           # Check auth status
momentium auth set-token                        # Set API key (interactive prompt)
pass show momentium/api-key | momentium auth set-token --stdin   # Set from pipe
momentium auth clear                            # Remove stored API key

User Profile

momentium me                                    # Show email and timezone
momentium me --json                             # Full profile as JSON
momentium me update --timezone "Pacific Time (US & Canada)"

Projects

# List projects
momentium projects list                                        # All projects
momentium projects list --month 2026-02                        # By month
momentium projects list --scheduling-state scheduled           # Scheduled only
momentium projects list --status active --priority             # Active priorities
momentium projects list --category tech                        # By category

# Note: --archived is INCLUSIVE — it adds archived projects to the default
# list rather than showing only archived ones. Piping it into a bulk delete
# deletes everything, so review `momentium projects list --archived` before
# `momentium projects list --archived -q | momentium projects delete --force`.
momentium projects list --archived                             # Include archived

# Create
momentium projects create "Build CLI" --category tech
momentium projects create "Vacation" --category travel --tag trip
momentium projects create "Q1 Goals" --month 2026-01 --scheduling-state scheduled --priority --tag q1

# Show / update
momentium projects show a1b2c3d4                               # Project details
momentium projects show a1b2c3d4 --tasks                       # With task list
momentium projects update a1b2c3d4 --status active
momentium projects prioritize a1b2c3d4                         # Toggle priority
momentium projects archive a1b2c3d4                            # Archive
momentium projects unarchive a1b2c3d4                          # Restore an archived project
momentium projects restore a1b2c3d4                            # Restore a soft-deleted project
momentium projects update a1b2c3d4 --tag infra --tag q3        # Replace tags
momentium projects update a1b2c3d4 --clear-tags                # Remove all tags

# Move between scheduling states
momentium projects move a1b2c3d4 --to backlog
momentium projects move a1b2c3d4 --to month --month 2026-03
momentium projects move a1b2c3d4 --to week --week 2026-W10

# Roll over incomplete projects
momentium projects rollover --from 2026-01 --to 2026-02

# Delete / restore
momentium projects delete a1b2c3d4
momentium projects delete a1b2c3d4 --force                     # Skip confirmation
momentium projects restore a1b2c3d4                            # Undo a soft-delete

Tasks

# List tasks
momentium tasks list --project a1b2c3d4                        # Tasks in a project
momentium tasks list --status todo --active                    # Active todos
momentium tasks list --priority high                           # High priority
momentium tasks list --all                                     # All pages

# Create
momentium tasks add "Fix login bug" --project a1b2c3d4
momentium tasks add "Write tests" --project a1b2c3d4 --priority high --tag tests
momentium tasks add "Quick fix" --project a1b2c3d4 --active

# Show / update
momentium tasks show a1b2c3d4                                  # Task details
momentium tasks update a1b2c3d4 --priority medium --notes "Updated plan"
momentium tasks update a1b2c3d4 --tag docs --tag launch
momentium tasks update a1b2c3d4 --clear-tags

# Lifecycle
momentium tasks activate a1b2c3d4                              # Focus on task
momentium tasks deactivate a1b2c3d4                            # Remove focus
momentium tasks done a1b2c3d4                                  # Mark complete
momentium tasks reopen a1b2c3d4                                # Undo completion
momentium tasks move a1b2c3d4 --project b2c3d4e5               # Move to another project
momentium tasks reorder --project a1b2c3d4 --ids b2c3d4e5,f6a7b8c9 # Set task order

# Delete / restore
momentium tasks delete a1b2c3d4
momentium tasks restore a1b2c3d4

Search

momentium search "launch marketing"
momentium search "launch" --table
momentium search "old notes" --include-done --include-archived
momentium search "launch" --no-backlog

Omitted include flags inherit the API defaults: done and archived records are excluded, backlog is included.

Now

The Now list is your hard-capped daily-commitment list (1–7 slots). Tasks completed today keep occupying a slot until the next local day unless refillSameDay is enabled.

# Show the current Now list (capacity, active + completed-today items)
momentium now list
momentium now list --table
momentium now list --json

# Include the event log (most recent 100 entries)
momentium now list --events

# Suggested tasks to focus on (up to 10, ranked)
momentium now suggestions

# Add / remove a task (full UUID or short-ID prefix)
momentium now add a1b2c3d4
momentium now remove a1b2c3d4

Adding a task fails with a structured error when the list is at capacity, the task is already on the list, or the task is not eligible.

Cycles

Cycles are recurring library items (weekly/monthly/quarterly/yearly) that materialize as occurrences per period.

Note: cycles current materializes the current period's occurrences on read — the same side effect as the web Cycles view. Repeated reads are idempotent: existing rows keep their status and action completion.

# Current occurrences grouped by cadence, with period keys and end dates
momentium cycles current
momentium cycles current --json

# Library items and their actions (--archived is INCLUSIVE — adds archived
# items to the default list)
momentium cycles library
momentium cycles library --archived

# Past-period occurrences, newest period first
momentium cycles history
momentium cycles history --cadence weekly
momentium cycles history --period-key 2026-W35
momentium cycles history --include-current

# Update an occurrence (full UUID or short-ID prefix)
momentium cycles update a1b2c3d4 --status done
momentium cycles update a1b2c3d4 --status skipped --notes "Out of town"

# Bulk-update status (atomic: any bad ID aborts the whole operation)
momentium cycles status a1b2c3d4 --status done
momentium cycles status a1b2c3d4 b2c3d4e5 --status done --force
momentium cycles current -q | momentium cycles status --status done --force

Statuses: unstarted, in_progress, done, skipped, not_applicable — --status values are validated client-side before any request is made.

The CLI intentionally covers only these five Cycles operations. Library authoring (create/update/reorder/archive/restore cycle items), occurrence action checking, and category management remain API-only.

Events

# List events
momentium events list --today                                  # Today's events
momentium events list --week                                   # This week (Sun–Sat)
momentium events list --month                                  # This month
momentium events list --from 2026-02-01 --to 2026-02-28        # Custom range
momentium events list --type appointment --week                # Filtered

# Create
momentium events create "Team sync" --date 2026-02-10 --start-time 10:00 --end-time 10:30
momentium events create "Deploy" --date today --type deadline
momentium events create "Vacation" --date 2026-03-01 --end-date 2026-03-07 --type travel

# Show / update
momentium events show a1b2c3d4
momentium events update a1b2c3d4 --start-time 11:00

# Move
momentium events move a1b2c3d4 --date tomorrow

# Delete / restore
momentium events delete a1b2c3d4
momentium events restore a1b2c3d4

Habits

# List habits (default: last 30 days, grouped by category, with a ✓/✗/· log grid)
momentium habits list
momentium habits list --from 2026-02-01 --to 2026-02-28            # Custom range
momentium habits list --archived                                   # Include archived habits

# Check off a day (idempotent — re-logging the same status succeeds)
momentium habits log a1b2c3d4 --completed                          # Today
momentium habits log a1b2c3d4 --missed --date 2026-03-01           # A specific day
momentium habits log a1b2c3d4 --clear                              # Remove a log

# Create / update
momentium habits add "Morning run"
momentium habits add "Meditate" --description "10 minutes" --start-date 2026-03-01
momentium habits add "Read" --category abc123def                   # Category UUID or ≥6 char prefix
momentium habits update a1b2c3d4 --title "Evening run"
momentium habits update a1b2c3d4 --category abc123def456           # Recategorize
momentium habits update a1b2c3d4 --clear-category                  # Remove category

habits list --json returns the full API payload (range, habits, logs, categories, today). Deliberately not covered: habit reorder, archive/restore/destroy, and all category-management operations — those stay in the app UI.

Trash

Deleted items (projects, tasks, and events) are soft-deleted first and kept in the trash for 30 days, then permanently destroyed by the API. daysRemaining in the output shows how long each item has left. Tasks discarded via a project cascade are not listed separately — they belong to the discarded project and are restored with it.

# List discarded items (newest-discard first)
momentium trash list                                            # All discarded items
momentium trash list --type projects                            # Discarded projects only
momentium trash list --json | jq '.tasks[].daysRemaining'

# Pair with restore to recover items before the 30 days run out
momentium projects restore a1b2c3d4

# Permanently destroy (destructive, unrecoverable — requires --force)
momentium trash destroy projects a1b2c3d4 --force               # One item
momentium trash empty --force                                   # ALL discarded items

trash destroy takes a positional <type> <id> pair. Without --force, trash empty and trash destroy prompt for confirmation in a TTY and refuse to run non-interactively. trash empty prints a per-type count of what it is about to destroy. Both commands are unrecoverable — anything they permanently destroy cannot be restored afterwards.

Output Formats

Control how data is displayed with format flags:

| Flag | Description | Default when | | ---------------- | -------------------------- | --------------- | | --plain | Human-readable styled text | stdout is a TTY | | --json | Machine-readable JSON | stdout is piped | | --table | Tabular format for lists | — | | --tsv | Tab-separated values | — | | --quiet / -q | Only IDs (full UUIDs) | — |

# Styled text (default in terminal)
momentium tasks list --project a1b2c3d4

# JSON output
momentium tasks list --project a1b2c3d4 --json

# Table output
momentium projects list --month 2026-02 --table

# TSV (paste into spreadsheets)
momentium events list --week --tsv

# Just IDs (for scripting)
momentium tasks list --project a1b2c3d4 -q

Short IDs

List views display truncated IDs (first 8 characters) for readability. The API supports prefix matching (≥6 chars), so you can use short IDs in commands:

momentium tasks show a1b2c3d4       # 8-char prefix — works fine
momentium tasks show a1b2c3d4e5f6   # Full UUID — also works

Detail views and --quiet mode always show full UUIDs.

Configuration

API Key

Your API key is resolved in this order:

MOMENTIUM_API_KEY environment variable
Config file (~/.config/momentium-cli/config.json)
Interactive prompt (TTY only)

The API key is never accepted as a CLI flag to avoid shell history exposure.

# Set via interactive prompt (recommended)
momentium auth set-token

# Set via environment variable
export MOMENTIUM_API_KEY=YOUR_API_KEY

# Set via pipe
pass show momentium/api-key | momentium auth set-token --stdin

Config File

Located at ~/.config/momentium-cli/config.json (respects XDG_CONFIG_HOME):

{
  "apiKey": "YOUR_API_KEY",
  "baseUrl": "https://www.momentium.app",
  "defaultFormat": "plain"
}

Environment Variables

| Variable | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | MOMENTIUM_API_KEY | API key (overrides config file) | | MOMENTIUM_BASE_URL | API base URL (default: https://www.momentium.app). Must use the www subdomain — the bare domain (momentium.app) issues a 301 redirect, and Node.js fetch strips the Authorization header on cross-origin redirects, breaking API auth. | | NO_COLOR | Disable all colors (see no-color.org) |

Scripting Recipes

Filter with jq

# Active project titles
momentium projects list --json | jq '.data[] | select(.status == "active") | .title'

# Count tasks by status
momentium tasks list --project a1b2c3d4 --all --json | jq '.data | group_by(.status) | map({status: .[0].status, count: length})'

# Today's event titles and times
momentium events list --today --json | jq '.data[] | "\(.startTime // "all-day") \(.title)"'

Bulk Operations with Pipes

# Complete all tasks in a project
momentium tasks list --project a1b2c3d4 -q | xargs -I{} momentium tasks done {}

# Bulk delete via stdin piping
momentium tasks list --project a1b2c3d4 -q | momentium tasks delete --force

# Undo a single soft-delete (IDs still work after DELETE until 30-day cleanup)
momentium tasks restore a1b2c3d4

# Delete all events this week
momentium events list --week -q | momentium events delete --force

Composing Commands

# Create a project, then add tasks to it
PROJECT_ID=$(momentium projects create "Sprint 5" --category tech -q)
momentium tasks add "Design review" --project "$PROJECT_ID"
momentium tasks add "Implementation" --project "$PROJECT_ID" --priority high
momentium tasks add "Write tests" --project "$PROJECT_ID"

# Export this month's projects to TSV
momentium projects list --month 2026-02 --tsv > february-projects.tsv

# Show pagination progress
momentium tasks list --all --verbose --project a1b2c3d4

Verbose & Debug Modes

# Show pagination progress
momentium tasks list --all --verbose --project a1b2c3d4

# Full debug output with stack traces
momentium tasks list --project a1b2c3d4 --debug

Development

Requires Node.js 22.21.0–22.x or 24.0.0+ and pnpm. Run pnpm install, then use pnpm dev -- --help for the development CLI. pnpm verify runs tests, linting, type checking, and formatting; CI runs those checks plus build, dependency audit, an OpenAPI drift check, and a packed-package consumer smoke test. Credentialed live tests are opt-in only and are never run in standard CI.

API drift

src/lib/types.ts is hand-maintained against momentium-app's public/api/v1/openapi.yaml. pnpm api:drift compares that spec's operationIds to src/lib/api-manifest.json and checks that covered operations map to real MomentiumClient methods.

When the app spec gains or loses an operation, the check fails with the operationId. Add { "client": "methodName" } for operations the CLI wraps, or { "uncovered": true } for ones it does not (cycle item authoring, occurrence actions, cycle categories, 10 of the 14 Habits operations, PUT replace).

Spec resolution: --spec <path>, then MOMENTIUM_OPENAPI_PATH, then a sibling ../momentium-app/public/api/v1/openapi.yaml checkout, then https://www.momentium.app/api/v1/openapi.yaml.

Contributing

Contributions are welcome! See CONTRIBUTING.md for setup instructions, development workflow, testing guide, and PR process.

Releasing

For maintainers: we use release-it to automate versioning, changelog updates, npm publishing, and GitHub releases.

pnpm release:dry    # Preview what will happen
pnpm release        # Run the release

See RELEASING.md for the full guide — prerequisites, step-by-step process, manual overrides, and configuration details.

License

MIT