Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

docs(cli): rewrite README with full command reference and collapsible details

Gener4dbacefae4bb
diff --git a/src/cli/README.md b/src/cli/README.md
index 041aac428..3eeb0da88 100644
--- a/src/cli/README.md
+++ b/src/cli/README.md
@@ -1,6 +1,6 @@
# @alook/cli
-Alook CLI — register and run always-on AI coding agents.
+Alook CLI — register machines, run the daemon, and manage agents from the command line.
## Install
@@ -8,39 +8,140 @@ Alook CLI — register and run always-on AI coding agents.
npx @alook/cli <command>
```
-Or install globally:
+## Quick Start
+
+1. Generate a machine token from the [Alook dashboard](https://alook.ai).
+2. Register this machine:
```bash
-npm install -g @alook/cli
-alook <command>
+npx @alook/cli register --token al_xxxxxxxxxxxxxxxxxxxxxxxx
```
-## Quick start
-
-Register this machine with your Alook account:
+3. Start the daemon:
```bash
-npx @alook/cli register --token al_xxxxxxxxxxxxxxxxxxxxxxxx
+npx @alook/cli daemon start
```
-You can generate a token from the Alook dashboard.
+The daemon runs in the background, polling for tasks and dispatching them to your local AI runtimes (Claude, Codex, or OpenCode).
## Commands
| Command | Description |
| --- | --- |
-| `alook register` | Register this machine with your Alook account. |
-| `alook status` | Show current registration status. |
-| `alook daemon` | Manage the local Alook daemon. |
-| `alook email` | Manage agent emails. |
-| `alook config` | Manage CLI configuration. |
-| `alook version` | Print the CLI version. |
+| `register --token <token>` | Register this machine with your Alook account |
+| `status` | Show registration status and linked workspace |
+| `daemon start` | Start the background daemon |
+| `daemon stop` | Stop the daemon |
+| `email pull --agent_id <id>` | Download agent emails |
+| `email send --agent_id <id> --to <addr> --subject "..." --body-file <path>` | Send an email |
+| `calendar set --agent_id <id> --event_title "..." --datetime <YYYY-MM-DDTHH:MM>` | Create a scheduled event |
+| `issue create --agent_id <id> --title "..."` | Create and dispatch an issue |
+| `sync upload-artifact --agent_id <id> --conversation_id <id> --file <path>` | Upload a file artifact |
+| `config show` | Show current configuration |
+| `update` | Update CLI to the latest version |
+| `version` | Print CLI version |
+
+Run `npx @alook/cli <command> --help` for all subcommand options.
+
+<details>
+<summary><strong>daemon</strong> — manage the background daemon</summary>
+
+```bash
+alook daemon start # Start in background
+alook daemon start --foreground # Start in foreground (for debugging)
+alook daemon stop # Stop the daemon
+alook daemon status # Check if the daemon is running
+```
+
+</details>
+
+<details>
+<summary><strong>email</strong> — pull, send, reply, forward, and manage sender whitelist</summary>
+
+```bash
+alook email pull --agent_id <id> # Download inbox
+alook email pull --agent_id <id> --status unread # Unread only
+alook email pull --agent_id <id> --folder sent # Sent emails
+alook email set --agent_id <id> --email_id <id> --status read # Mark as read
+
+alook email send --agent_id <id> --to <addr> --subject "Hi" --body-file body.html
+alook email send ... --in-reply-to <email_id> # Reply to a thread
+alook email send ... --attachment report.pdf # Attach a file
+alook email forward --agent_id <id> --email_id <id> --to <addr> --note "FYI"
+
+alook email whitelist list --agent_id <id> # List allowed senders
+alook email whitelist add --agent_id <id> <email> # Allow a sender
+alook email whitelist delete --agent_id <id> <email> # Remove a sender
+```
+
+Options: `--from <addr>` to send from a custom mailbox, `--limit <n>` / `--offset <n>` for pagination, `--json` for machine-readable output.
+
+</details>
+
+<details>
+<summary><strong>calendar</strong> — schedule one-off or recurring agent events</summary>
+
+When an event fires, a new task is dispatched to the agent with the event title as the prompt.
+
+```bash
+alook calendar set --agent_id <id> --event_title "Daily standup" --datetime 2026-05-16T09:00
+alook calendar set ... --repeat 1week --repeat_stop_date 2026-12-31
+
+alook calendar list --agent_id <id> # List upcoming events
+alook calendar show --agent_id <id> --event_id <id> # Show full detail
+alook calendar update --agent_id <id> --event_id <id> --datetime 2026-05-17T10:00
+alook calendar delete --agent_id <id> --event_id <id>
+```
+
+Datetime is always local time (`YYYY-MM-DDTHH:MM`). Repeat intervals: `1hour`, `1day`, `1week`, `1month`, etc.
+
+</details>
+
+<details>
+<summary><strong>issue</strong> — create and manage issues assigned to agents</summary>
+
+```bash
+alook issue create --agent_id <id> --title "Fix login bug"
+alook issue create --agent_id <id> --title "Refactor auth" --body-file spec.md
+
+alook issue list --agent_id <id> # Active issues
+alook issue list --agent_id <id> --completed # Completed/closed issues
+alook issue show --agent_id <id> --issue_id <id> # Full detail + conversation
+alook issue update --agent_id <id> --issue_id <id> --status done
+alook issue comment --agent_id <id> --issue_id <id> --body "Looks good"
+```
+
+Statuses: `todo`, `in_progress`, `review`, `done`, `closed`, `canceled`, `failed`.
+
+</details>
+
+<details>
+<summary><strong>config</strong> — manage CLI configuration</summary>
-Run `alook <command> --help` for subcommand options.
+```bash
+alook config show # Show current config
+alook config path # Show config file path
+```
+
+Config is stored at `~/.alook/config.json` and includes:
+
+- `server_url` — Alook server URL
+- `profiles` — per-profile settings with workspace bindings
+- `watched_workspaces` — workspaces the daemon monitors (each with `id`, `name`, `token`, `agent_ids`)
+
+</details>
+
+## Global Options
+
+```
+--server <url> Override server URL
+--profile <name> Use a specific config profile
+```
## Requirements
-- Node.js ≥ 20
+- Node.js >= 20
## License