Metadata-Version: 2.4
Name: lifeos-cli
Version: 0.16.0
Summary: Command-line tooling for personal operating system workflows, tools, and automation.
Author: liujuanjuan1984
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/liujuanjuan1984/lifeos-cli
Project-URL: Repository, https://github.com/liujuanjuan1984/lifeos-cli
Project-URL: Issues, https://github.com/liujuanjuan1984/lifeos-cli/issues
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: alembic<2.0,>=1.16
Requires-Dist: aiosqlite<1.0,>=0.21
Requires-Dist: pyfiglet<2.0,>=1.0
Requires-Dist: python-dateutil<3.0,>=2.9
Requires-Dist: sqlalchemy<3.0,>=2.0
Requires-Dist: tomli<3.0,>=2.3; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: mypy<3.0,>=1.18; extra == "dev"
Requires-Dist: pip-audit<3.0,>=2.9; extra == "dev"
Requires-Dist: pre-commit<5.0,>=4.5.0; extra == "dev"
Requires-Dist: pytest<10.0,>=8.4; extra == "dev"
Requires-Dist: ruff<0.16,>=0.11; extra == "dev"
Requires-Dist: types-python-dateutil<3.0,>=2.9.0.20241206; extra == "dev"
Requires-Dist: vulture<3.0,>=2.14; extra == "dev"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]<4.0,>=3.2; extra == "postgres"
Provides-Extra: web
Requires-Dist: fastapi<1.0,>=0.115; extra == "web"
Requires-Dist: uvicorn[standard]<1.0,>=0.30; extra == "web"
Dynamic: license-file

# lifeos-cli

[简体中文版](README.zh-Hans.md)

```text
██╗     ██╗███████╗███████╗ ██████╗ ███████╗
██║     ██║██╔════╝██╔════╝██╔═══██╗██╔════╝
██║     ██║█████╗  █████╗  ██║   ██║███████╗
██║     ██║██╔══╝  ██╔══╝  ██║   ██║╚════██║
███████╗██║██║     ███████╗╚██████╔╝███████║
╚══════╝╚═╝╚═╝     ╚══════╝ ╚═════╝ ╚══════╝
```

`lifeos-cli` is a terminal-native LifeOS for people who want one structured system for intentions, plans, execution, reflection, and reality.

## 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 unnecessarily hard to answer practical questions such as:

- 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?

It gives structure to both sides of life:

- intention: visions, tasks, habits, and planned events
- reality: notes, timelogs, completed habit actions, and relationship records

The goal is not just storage, but one CLI interface for self-management, reflection, and automation.

## Getting Started

Install or upgrade from PyPI:

```bash
uv tool install --upgrade lifeos-cli
```

Install PostgreSQL support only when you need it:

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

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

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

`lifeos-cli` supports both 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:

```bash
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.

You can run that step yourself, or ask an agent that can run terminal commands to do it for you.

See the available command surface:

```bash
lifeos --help
```

Start the local Web API server:

```bash
lifeos web serve
```

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

```bash
lifeos web serve --static-dir web/dist
```

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

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

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

```bash
cd web
npm install
npm run dev
```

Inspect and adjust runtime preferences:

```bash
lifeos config show
lifeos config set preferences.timezone America/Toronto
lifeos config set preferences.language zh-Hans
```

Common commands:

```bash
lifeos schedule show --date 2026-04-13
lifeos task list
lifeos note add "Capture today's key decisions"
lifeos timelog list --date 2026-04-13
```

For complete CLI usage, workflows, and output conventions, see [docs/cli.md](docs/cli.md).

## Agent Use (Recommended)

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`

## Current Scope

The current system already covers the core building blocks of a practical LifeOS:

- notes
- areas
- tags
- people
- visions
- tasks
- habits and habit actions
- events
- timelogs

Cross-cutting capabilities:

- a `schedule` read model that aggregates tasks, habit actions, and planned events into day and range views
- recurring event expansion and recurring habit cadence support, including on-demand habit-action materialization
- generic note associations across tasks, visions, events, people, timelogs, and tags
- persisted runtime configuration for database access plus preferences such as timezone, language, day boundary, week boundary, and vision experience defaults
- localized CLI help and stable summary-table output for direct human use and agent consumption

## Project Policies

- Contribution workflow: [CONTRIBUTING.md](CONTRIBUTING.md)
- Security disclosure: [SECURITY.md](SECURITY.md)
- Community expectations: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)

## License

This project is licensed under the Apache License 2.0. See [LICENSE](LICENSE).
