---
name: treehouse-cli
description: Use the treehouse CLI to manage the Treehouse platform — tenants, agents, apps, credentials, nanoclaw service, backups, MC tasks (Mission Control tracked work items), and domains. Prefer this over ad-hoc shell commands for all operational tasks.
allowed-tools: Bash
---

# Treehouse Admin CLI

The `treehouse` CLI is the canonical operational tool for the Treehouse platform. Use it instead of raw shell commands whenever possible.

> **Inside the admin container:** access is via SSH to the host first:
> ```bash
> ssh -o UserKnownHostsFile=/home/node/.ssh/known_hosts -o StrictHostKeyChecking=yes -o UpdateHostKeys=no admin@172.17.0.1
> ```
> Then run `treehouse <command>` on the host.

## Command Reference

| Command | Purpose |
|---------|---------|
| `treehouse doctor [--json]` | Full platform health check — services, caddy config, backup recency, tenant volumes, runtimes, stuck containers, app drift, and buildkit churn. Exit 0=ok, 1=warnings, 2=failures. |
| `treehouse defaults get/set` | Platform-wide provider/model defaults |
| `treehouse agents ps` | List running agent containers |
| `treehouse agents kill` | Kill agent containers (`--tenant`, `--id`, `--all`) |
| `treehouse agents logs --id <id>` | Tail a running agent container's output |
| `treehouse tenants list` | List all tenants |
| `treehouse tenants show --tenant <id>` | Show tenant detail |
| `treehouse tenants create` | Provision a new tenant |
| `treehouse tenants update --tenant <id>` | Update tenant config |
| `treehouse tenants clear-runtime-overrides [--tenant <id>]` | Clear per-tenant provider/model overrides so tenants inherit global defaults |
| `treehouse tenants remove --tenant <id>` | Delete a tenant |
| `treehouse tenants usage` | Today's per-tenant usage |
| `treehouse tenants ports` | Tenant port allocations |
| `treehouse tenants tailscale-proxy --tenant <id> [--enable|--disable] [--yes]` | Enable or disable Tailscale exit-node SOCKS5 proxy access for a tenant (requires nixos-rebuild, ~30s) |
| `treehouse apps list` | List deployed tenant apps |
| `treehouse apps ps` | Running app containers (all tenants) |
| `treehouse apps deploy --tenant <id> --app <app> [--force-rebuild]` | Trigger a host-side app deploy from `/workspace/apps/<app>/app.yml` |
| `treehouse apps remove --tenant <id> --app <app>` | Trigger app removal through the authoritative host lifecycle |
| `treehouse apps status --tenant <id> [--app <name>]` | Authoritative app inventory for a tenant — DB/Caddy/systemd/runtime/status drift in one view |
| `treehouse apps ports --tenant <id>` | Authoritative host-port view derived from DB, Caddy, and live containers |
| `treehouse apps reconcile --tenant <id> [--app <app>] [--fix]` | Detect or repair app control-plane drift |
| `treehouse apps smoke --tenant <id> [--app <app>]` | End-to-end lifecycle smoke test: create, update, restart, remove, and cleanup a synthetic app |
| `treehouse apps logs --tenant <id> --name <c>` | Tail tenant app container logs |
| `treehouse apps restart --tenant <id> --app <app>` | Restart a tenant app |
| `treehouse apps images [--tenant <id>] [--all]` | List images in tenant rootless containerd (all tenants if no filter) |
| `treehouse apps image-prune [--tenant <id>] [--all]` | Prune dangling images (or all unused with `--all`); omit `--tenant` to prune all tenants. WARNING: `--all` removes built app images — apps need rebuild after. |
| `treehouse apps image-rm --tenant <id> --image <image>` | Remove a specific image from a tenant's containerd |
| `treehouse apps clean-stuck --tenant <id> [--app <app>]` | Fix root-owned oplock dirs and force-remove stopped containers stuck in nerdctl's name store |
| `treehouse runtime ping` | Ping tenant rootless containerd runtimes |
| `treehouse runtime df` | Disk usage per tenant volume (nerdctl/containerd breakdown) |
| `treehouse volumes list` | List all tenant volumes: limit, image size, used, free |
| `treehouse volumes resize --tenant <id> --size <MB>` | Resize a tenant volume (grow online; shrink requires brief unmount) |
| `treehouse caddy lint` | Validate all Caddyfiles |
| `treehouse caddy reload` | Reload Caddy config |
| `treehouse creds list` | List credential pool entries |
| `treehouse creds show --id <id>` | Show full credential detail |
| `treehouse creds create --id <id> --type <oauth\|apikey> [--set k=v ...]` | Create a credential |
| `treehouse creds update --id <id> [--set k=v ...]` | Update credential fields |
| `treehouse creds login --id <id>` | Start OAuth login for a credential |
| `treehouse creds import-auth --id <id>` | Import pre-existing auth tokens |
| `treehouse creds logout --id <id>` | Revoke and clear stored tokens |
| `treehouse creds resume --id <id>` | Resume a paused OAuth session |
| `treehouse creds login-status --id <id>` | Check OAuth login state |
| `treehouse creds usage --id <id>` | Show credential usage stats |
| `treehouse creds callback --id <id> --code <code>` | Complete OAuth callback manually |
| `treehouse creds remove --id <id>` | Delete a credential |
| `treehouse nanoclaw status` | NanoClaw service status |
| `treehouse nanoclaw logs [--lines N]` | Recent nanoclaw logs |
| `treehouse nanoclaw hup` | Hot-reload tenants/groups (no restart) |
| `treehouse nanoclaw restart` | Full service restart (destructive — confirm first) |
| `treehouse backups status` | Borgmatic backup status |
| `treehouse backups run` | Trigger a manual backup |
| `treehouse mc restart [--build-ui]` | Restart Mission Control (optionally rebuild UI) |
| `treehouse chats list` | List chats per tenant |
| `treehouse messages tail [--tenant <id> \| --chat_jid <jid> \| --group <tenant/group>]` | Tail inbound messages — filter by tenant, chat JID, or exact group folder |
| `treehouse session tail --group <tenant/group> [--limit N]` | Show recent conversation turns (both user and agent) for a group, interleaved |
| `treehouse groups list [--tenant <id>]` | List registered groups |
| `treehouse groups show --folder <tenant/group>` | Show detail for a specific group |
| `treehouse groups dangling [--tenant <id>] [--delete]` | Find groups with no matching filesystem folder; `--delete` removes them |
| `treehouse groups hooks --folder <tenant/group>` | Show hooks config (token, enabled state) for a group |
| `treehouse groups hooks enable/disable --folder <tenant/group>` | Enable or disable hooks for a group |
| `treehouse groups hooks rotate --folder <tenant/group>` | Rotate the hooks bearer token for a group |
| `treehouse groups hooks-list [--tenant <id>] [--json]` | List hooks status (token + enabled/disabled) for all groups — optionally filtered by tenant |
| `treehouse groups hooks-find --token <token>` | Reverse-lookup: find which tenant/group owns a given hooks token |
| `treehouse groups hooks-enable-all [--yes]` | Enable hooks on every group that does not already have it enabled; generates tokens as needed |
| `treehouse bots list [--json]` | List all Discord bot tenants (name, user ID, token preview) |
| `treehouse bots send --tenant <id> --channel <jid-or-id> --message <text>` | Send a message from a bot tenant directly to a Discord channel (accepts `dc:` JID or raw channel ID) |
| `treehouse discord members [--limit N] [--json]` | List Discord guild members sorted by join date (newest first) |
| `treehouse discord welcome-check [--bot-tenant <id>] [--days N] [--json]` | Check if Gaia (or another bot tenant) sent a DM to each member who joined in the last N days (default: 1 day, bot: gaia) |
| `treehouse mctasks list [--status <s>]` | List MC tasks (filter: open/in_progress/done/cancelled) |
| `treehouse mctasks show --id <taskId>` | Full task detail |
| `treehouse mctasks create --title <t> [--description <d>] [--status <s>] [--priority <p>]` | Create a task |
| `treehouse mctasks update --id <taskId> [--status <s>] [--title <t>]` | Update a task |
| `treehouse mctasks comment --id <taskId> --text <text>` | Add a comment |
| `treehouse mctasks delete --id <taskId>` | Delete a task |
| `treehouse domains list [--tenant <id>]` | List custom domains |
| `treehouse domains show --id <domainId>` | Show domain detail and verification status |
| `treehouse domains add --tenant <id> --domain <domain> [--target dashboard\|<subdomain>]` | Register a custom domain |
| `treehouse domains activate --id <domainId>` | Activate a verified domain |
| `treehouse domains remove --id <domainId>` | Remove a custom domain |
| `treehouse tasks list [--tenant <id>]` | List NanoClaw scheduled tasks (agent-created, not MC tasks) |
| `treehouse tasks show --id <taskId>` | Show scheduled task detail |
| `treehouse tasks logs --id <taskId>` | Recent run logs for a scheduled task |
| `treehouse tasks watch` | Live-watch scheduled task activity |
| `treehouse tasks pause/resume/cancel --id <taskId>` | Manage a scheduled task |
| `treehouse ui screenshot [--path /credentials] [--out /tmp/mc-ui.png]` | Screenshot the Mission Control UI |
| `treehouse announce <message>` | Post a message to all registered `#announcements` channels via treebot |

## Common Workflows

```bash
# Full platform health check (human-readable)
treehouse doctor

# Same check, structured JSON output (exit 0/1/2)
treehouse doctor --json

# What agent containers are running?
treehouse agents ps

# Kill stuck agents for a tenant
treehouse agents kill --tenant <id> --all --yes

# Hot-reload after DB changes (preferred over restart)
treehouse nanoclaw hup

# Check per-tenant disk usage (filesystem view)
treehouse volumes list

# Resize a tenant volume
treehouse volumes resize --tenant <id> --size <MB> --yes

# Check nerdctl/containerd disk usage inside a tenant
treehouse runtime df

# Restart MC after code changes
treehouse mc restart --build-ui --yes

# Reconcile app hosting drift for one tenant
treehouse apps reconcile --tenant koala --fix

# Run the end-to-end app lifecycle smoke harness
treehouse apps smoke --tenant koala --yes

# Today's usage breakdown
treehouse tenants usage

# Read the last 20 turns (user + agent) for a channel
treehouse session tail --group koala/general

# Read only inbound user messages for a specific channel
treehouse messages tail --group koala/general --limit 30
```

## Rules

- Prefer `treehouse nanoclaw hup` over `restart` for DB-only changes — restart kills active containers.
- Always pass `--yes` only after confirming destructive actions with the user.
- Use `--json` flag for programmatic output when piping or processing results.
- **After adding or modifying any CLI command, update this SKILL.md** so agents have accurate documentation. Also update any relevant platform or admin skills (`skills-platform/`, `skills-admin/`) if the change affects agent-facing behaviour.
