sunwaee 1.0.1

SUNWÆE CLI — The Almost Everything CLI

SUNWAEE CLI

The Almost Everything CLI - The command-line interface for SUNWAEE.

Used as a daily driver by human users and as a structured interface by Sun, the SUNWAEE AI agent.

---

Installation

pip install sunwaee

Or for local development:

git clone https://github.com/sunwaee/cli
cd cli
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

The binary is sunwaee.

---

Usage

sunwaee --help
sunwaee workspace --help
sunwaee note --help
sunwaee task --help
sunwaee log --help

Init

Run once after installation to create the config file and default workspace:

sunwaee init                          # creates 'personal' workspace (default)
sunwaee init --workspace pro          # creates a custom default workspace
sunwaee init --force                  # re-initialise even if already set up

Workspaces

All data is organized by workspace. Use sunwaee init on first run, or manage workspaces manually:

sunwaee workspace create personal
sunwaee workspace create pro
sunwaee workspace list
sunwaee workspace set-default pro
sunwaee workspace delete personal --confirm

Notes

Commands that look up a note (show, edit, delete) search all workspaces by default. Pass --workspace to scope to one.

list returns results from all workspaces by default and includes a Workspace column in the output.

sunwaee note create --title "Meeting notes" --tags "work,q1" --body "Discussed roadmap."
sunwaee note create --title "Ideas" --workspace personal    # create always uses default workspace

sunwaee note list                         # all workspaces
sunwaee note list --workspace pro         # single workspace
sunwaee note list --tags work
sunwaee note list --query "roadmap"       # search by title, tags, or body
sunwaee note list --sort title            # updated (default), created, title

sunwaee note show "Meeting notes"         # finds across all workspaces
sunwaee note show "Meeting notes" --workspace pro

sunwaee note edit "Meeting notes" --body "Updated content."
sunwaee note delete "Meeting notes" --confirm

Tasks

Commands that look up a task (show, edit, complete, uncomplete, delete) search all workspaces by default. Pass --workspace to scope to one.

list returns results from all workspaces by default and includes a Workspace column in the output.

# Create (always targets default workspace unless --workspace is passed)
sunwaee task create --title "Fix login bug" --priority high --due 2026-03-01 --tags "dev"
sunwaee task create --title "Write docs" --priority low --workspace pro
sunwaee task create --title "Quick task" --due today

# List — all workspaces, completed tasks hidden by default
sunwaee task list
sunwaee task list --workspace pro           # single workspace
sunwaee task list --status todo --priority high
sunwaee task list --due today               # today, tomorrow, this-week, this-month, overdue, YYYY-MM-DD
sunwaee task list --query "login"           # search by title, tags, or body
sunwaee task list --sort priority           # updated (default), created, title, due, priority
sunwaee task list --show-completed          # include completed tasks

# Show / complete / uncomplete (search across all workspaces)
sunwaee task show "Fix login bug"
sunwaee task complete "Fix login bug"
sunwaee task uncomplete "Fix login bug"

# Edit
sunwaee task edit "Fix login bug" --status in_progress --tags "dev,urgent"
sunwaee task edit "Fix login bug" --due tomorrow
sunwaee task edit "Fix login bug" --clear-due  # remove due date

sunwaee task delete "Fix login bug" --confirm

Subtasks

Use --parent to link a task to a parent. task complete and task delete cascade to all children.

sunwaee task create --title "Sub Task" --parent "Fix login bug"

# Completing or deleting a parent also affects all its children
sunwaee task complete "Fix login bug"
sunwaee task delete "Fix login bug" --confirm

task list displays subtasks indented under their parent. task show lists children inline.

Logs

Every command that mutates data (create, edit, delete, complete, uncomplete, set-default) automatically appends an entry to the workspace activity log. List commands (note list, task list, log list) are also logged with their active filters and result count.

sunwaee log list                              # today's logs, all workspaces
sunwaee log list --workspace personal         # single workspace
sunwaee log list --date 2026-03-01            # specific day (YYYY-MM-DD)
sunwaee log list --month 2026-03              # full month (YYYY-MM)
sunwaee log list --all                        # all time
sunwaee log list --module notes               # filter by module
sunwaee log list --operation create           # filter by operation
sunwaee log list --caller sun                 # filter by caller (human, api, sun)
sunwaee log list --query "meeting"            # free-text search
sunwaee log list --limit 20                   # max entries (default: 50)

Logs are stored as append-only JSON Lines files and are never deleted:

<workspace>/logs/<year>/<month>/<day>/logs.jsonl

Each entry includes timestamp, caller, workspace, module, operation, ok, and optionally item_id, item_title, and args (active filters + result count for list operations).

---

Configuration

On first run, a config file is created at ~/.sunwaee/config.toml:

[workspaces]
default = "personal"
base_dir = "~/sunwaee/workspaces"

Any value can be overridden with environment variables:

Variable	Default	Description
SUNWAEE_CONFIG_DIR	~/.sunwaee	Config directory
SUNWAEE_WORKSPACES_DIR	~/sunwaee/workspaces	Workspaces base directory
SUNWAEE_WORKSPACE	personal	Active workspace (overrides config)
SUNWAEE_CALLER	human	Caller context (see below)
SUNWAEE_LOG_LEVEL	warning	Log level (debug, info, warning, error, critical)

---

Caller Modes

The SUNWAEE_CALLER environment variable controls output format and behavior.

Value	Output	Set by
human	Rich colored output	Default (terminal users)
api	JSON	SUNWAEE app API (docker exec / SSH)
sun	JSON	Sun AI agent

Success response (api/sun):

{"ok": true, "data": {...}}

Error response (any caller):

{ "ok": false, "error": "Note not found", "code": "NOT_FOUND" }

Error codes: NOT_FOUND, ALREADY_EXISTS, VALIDATION_ERROR, IO_ERROR, CONFIRMATION_REQUIRED.

---

Data Storage

Data is stored as Markdown files with YAML frontmatter - human-readable and Git-friendly.

~/sunwaee/workspaces/
├── personal/
│   ├── notes/
│   │   └── meeting-notes.md
│   ├── tasks/
│   │   └── fix-login-bug.md
│   └── logs/
│       └── 2026/
│           └── 03/
│               └── 02/
│                   └── logs.jsonl
└── pro/
    ├── notes/
    ├── tasks/
    └── logs/

Note (~/sunwaee/workspaces/<workspace>/notes/<slug>.md):

---
id: b80543a8-5039-461b-8257-dd926f4bc5bb
title: Meeting notes
tags:
  - work
  - q1
created_at: "2026-02-27T23:24:05.330348+00:00"
updated_at: "2026-02-27T23:24:05.330357+00:00"
---

Note body in Markdown.

Task (~/sunwaee/workspaces/<workspace>/tasks/<slug>.md):

---
id: 707a888f-f0b0-49d1-a878-78df9c932c24
title: Fix login bug
status: todo
priority: high
due_date: "2026-03-01"
tags:
  - dev
parent_id: null
completed_at: null
created_at: "2026-02-27T23:24:14.253188+00:00"
updated_at: "2026-02-27T23:24:14.253195+00:00"
---

Task description in Markdown.

---

Adding a Module

The CLI auto-discovers modules. To add a new domain:

1. Create sunwaee/modules/<name>/ with __init__.py, model.py, commands.py
2. Export app = typer.Typer(name="<name>", ...) in __init__.py
3. Done — no changes to core code required

Data for the new module lives at ~/sunwaee/workspaces/<workspace>/<name>/.

---

License

MIT