sunwaee 1.0.0

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

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

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

sunwaee note list
sunwaee note list --workspace pro
sunwaee note list --tags work
sunwaee note list --sort title            # updated (default), created, title

sunwaee note show "Meeting notes"
sunwaee note show "Meeting notes" --workspace pro

sunwaee note edit "Meeting notes" --body "Updated content."
sunwaee note search "roadmap"
sunwaee note search "roadmap" --workspace pro
sunwaee note delete "Meeting notes" --confirm

Tasks

# Create
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 — completed tasks are hidden by default
sunwaee task list
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 --sort priority           # updated (default), created, title, due, priority
sunwaee task list --show-completed          # include completed tasks

# Show / complete / uncomplete
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 search "login"
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.

---

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
└── pro/
    ├── notes/
    └── tasks/

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