lifeos-cli

简体中文版

██╗     ██╗███████╗███████╗ ██████╗ ███████╗
██║     ██║██╔════╝██╔════╝██╔═══██╗██╔════╝
██║     ██║█████╗  █████╗  ██║   ██║███████╗
██║     ██║██╔══╝  ██╔══╝  ██║   ██║╚════██║
███████╗██║██║     ███████╗╚██████╔╝███████║
╚══════╝╚═╝╚═╝     ╚══════╝ ╚═════╝ ╚══════╝

lifeos-cli is a terminal-native, local-first LifeOS for quantified-self workflows. It gives one structured system for intentions, plans, execution, relationships, money, reflection, and measured reality.

The product surface is already broad and deep: a typed Python CLI as the primary interface, SQLite and PostgreSQL backends, Alembic migrations, a local FastAPI service, and a first-party React Web UI for human browser workflows over the same configured LifeOS database. The CLI is designed to be both human-usable and agent-friendly, with stable command grammar, help-first documentation, identifier-driven flows, and predictable text output.

Why It Exists

Most personal systems fragment life into disconnected tools. Tasks live in one place, calendars in another, notes somewhere else, and actual time spent disappears into scattered logs. That makes it hard to answer practical questions:

• What did I intend to do?
• What actually happened?
• What did I spend time on?
• Which routines are real versus aspirational?
• Which people, projects, and priorities am I actually serving?
• How do my plans, time, habits, notes, relationships, and finances connect?

lifeos-cli treats a personal operating system as both a planning graph and an evidence ledger:

• intention: areas, visions, tasks, habits, planned events, and finance structures
• reality: timelogs, habit actions, notes, relationship records, finance snapshots, and aggregate stats

The goal is not just storage. The goal is a coherent command and API surface that humans and agents can use to capture life as it happens, inspect it later, and automate repeatable self-management workflows.

Current Capability Map

The implemented system covers the main quantified-self loop from planning to evidence to review.

Interfaces

The terminal-native CLI is the primary product interface and command reference:

lifeos --help
lifeos <resource> --help
lifeos <resource> <action> --help

The command shape is intentionally stable:

lifeos <resource> <action> [arguments] [options]

This shape is intentionally friendly to both humans and agents. Humans get explicit, discoverable commands; agents get deterministic help, stable identifiers, compact tabular list output, and labeled detail output.

The local Web UI is the human browser interface for the same LifeOS data. It is first-party and intentionally local: the Web API and UI use the same configured database as the CLI and are not a separate hosted service.

Getting Started

Install or upgrade from PyPI:

uv tool install --upgrade lifeos-cli

Install PostgreSQL support only when you need it:

uv tool install --upgrade "lifeos-cli[postgres]"

Install the optional local Web API and Web UI runtime dependencies when you want human browser access or HTTP access backed by the same configured LifeOS database:

uv tool install --upgrade "lifeos-cli[web]"

lifeos-cli supports SQLite and PostgreSQL.

• SQLite is the low-friction option for local, single-user setups.
• PostgreSQL remains the schema-capable backend for managed deployments.

Initialize your local setup:

lifeos init

For local-first use, lifeos init can bootstrap SQLite without requiring a separate database service. Use lifeos init --help for backend-specific defaults and examples.

Inspect and adjust runtime preferences:

lifeos config show
lifeos config set preferences.timezone America/Toronto
lifeos config set preferences.language zh-Hans
lifeos config set preferences.day_starts_at 04:00
lifeos config set preferences.week_starts_on monday

Common CLI Workflows

lifeos area add "Health" --color "#16A34A" --icon heart
lifeos vision add "Build a stronger health baseline" --area-id <area-id>
lifeos task add "Train three times this week" --vision-id <vision-id> --planning-cycle-type week --planning-cycle-days 7 --planning-cycle-start-date 2026-04-13
lifeos event add "Strength training" --start-time 2026-04-13T18:00:00 --end-time 2026-04-13T19:00:00 --task-id <task-id>
lifeos schedule show --date 2026-04-13
lifeos timelog add "Workout" --start-time 2026-04-13T18:00:00 --end-time 2026-04-13T19:00:00 --task-id <task-id>
lifeos habit add "Morning mobility" --start-date 2026-04-01 --duration-days 100 --cadence-frequency daily
lifeos habit-action log --habit-id <habit-id> --date 2026-04-13 --status done
lifeos note add "Energy was higher after sleeping earlier." --task-id <task-id>
lifeos finance tree-ensure-default
lifeos data export all --output lifeos-bundle.zip

For complete CLI usage, workflows, and output conventions, see docs/cli.md. Command-specific facts belong in CLI help, not in repository-level docs.

Local Web UI

Start the local Web API server for browser access:

lifeos web serve

lifeos web serve does not install, build, or bundle the frontend workspace from PyPI. To serve the human Web UI from the same process in a source checkout, build web/ and pass its output directory explicitly:

lifeos web serve --static-dir web/dist

If your configured database URL uses PostgreSQL, install or run with both optional extras:

uv run --extra web --extra postgres lifeos web serve

During frontend development, run the human-facing Vite app in web/ and proxy API requests to the local Web API:

cd web
npm install
npm run dev

See web/README.md for frontend workspace details.

Agent Use

Any agent runtime that can execute terminal commands and inspect command output can operate the same CLI. That includes Codex, OpenCode, Swival, Claude Code, Cursor, Gemini CLI, OpenClaw, or your own setup.

• stable grammar: lifeos <resource> <action> [arguments] [options]
• help-first command model, with --help as the primary command reference
• identifier-driven discovery flows built around list and show
• compact summary output for lists and labeled output for record detail views
• entity-specific primary-key headers such as task_id, vision_id, and event_id
• persisted language preference so agents can match human-authored payload language
• data import/export commands for machine-generated cleanup, migration, and backup flows

Development Validation

For repository changes, run the primary validation entrypoint:

bash ./scripts/doctor.sh

For CLI documentation review, the help audit script executes the parser tree and renders a Markdown report:

uv run python scripts/audit_cli_help.py

Project Policies

• Contribution workflow: CONTRIBUTING.md
• Security disclosure: SECURITY.md
• Community expectations: CODE_OF_CONDUCT.md

License

This project is licensed under the Apache License 2.0. See LICENSE.