# SUNWAEE CLI

The Almost Everything CLI - The command-line interface for [SUNWAEE](https://sunwaee.com).

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

---

## Installation

```bash
pip install sunwaee
```

Or for local development:

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

```bash
sunwaee --help
sunwaee workspace --help
sunwaee note --help
sunwaee task --help
```

### Init

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

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

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

### Notes

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

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

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

```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):**

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

**Error response (any caller):**

```json
{ "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`):

```markdown
---
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`):

```markdown
---
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](LICENSE)
