---
name: treehouse-tc
description: INVOKE THIS FIRST before using tc CLI, checking credentials, or interacting with platform state. Use the tc CLI to interact with the Treehouse platform from within the agent container — deploy apps, send messages, manage tasks, inspect platform state, and more. Use `tc report` to file bug reports or feedback to the platform admin.
---

# Treehouse CLI (`tc`)

`tc` is the Treehouse platform CLI, available in all agent containers. It is a thin wrapper around `@treehouse/sdk` and communicates with the host via IPC file-drops.

## Usage

```bash
tc <command> [args]
tc --help
```

## Commands

### Identity
```bash
tc whoami                    # Print your tenant ID
```

### Memory (LCM)
```bash
tc memory search <query>            # Hybrid search (default) — merges keyword + semantic via RRF
tc memory search --semantic <query> # Pure semantic/embedding search — concepts, synonyms, related topics
tc memory search --match <query>    # Pure keyword/FTS search — exact names, identifiers, quoted phrases
tc memory describe [id]             # Show LCM DB stats, or expand a summary node by ID
```

### Apps
```bash
tc app deploy <app> [--force-rebuild]       # Trigger app-apply; --force-rebuild forces full image rebuild
tc app remove <app>                     # Remove an app
tc app stop <app>                       # Stop an app (compose-stop)
tc app restart <app> [--service <svc>]  # Force-recreate containers
tc app logs <app> <svc> [--tail N]      # Fetch container logs
tc app exec <app> <svc> -- <cmd...>     # Exec a command in a running container
tc app volumes <app>                    # List named volumes for an app
tc app volumes remove <app> <vol>       # Remove a named volume (app must be stopped)
tc app status [<app>]                   # Show deploy status (all apps or one)
tc app wait <app> [--timeout N]        # Wait for deploy to complete (default: 120s)
tc app errors [--limit N]              # Show recent deploy errors (default: 5)
```

`tc app deploy <app>` is the normal deploy path. It reads `/workspace/apps/<app>/app.yml`, asks the host to allocate or reuse a safe host port, and builds before restarting runtime if the app has build services. Do not add `ports:` to `app.yml`.

### Hosting info
```bash
tc hosting info                         # Show hosting metadata (port range, IPC paths)
```

### Messaging
```bash
tc send <text>                             # Send a message to the current chat
tc send --group <jid> <text>               # Send a message to a specific group by JID
tc send file <path> [--caption <text>]  # Send a file attachment
tc send voice <text>                    # Synthesize and send a voice message
```

### Tasks
```bash
tc tasks                                              # List scheduled tasks
tc tasks schedule --type cron --value "0 9 * * *" "Daily briefing"
tc tasks schedule --type interval --value 3600000 "Check status"
tc tasks schedule --type once --value "2026-04-01T09:00:00" "Reminder"
tc tasks pause <id>                                   # Pause a task
tc tasks resume <id>                                  # Resume a task
tc tasks cancel <id>                                  # Cancel and delete a task
tc tasks update <id> [--prompt <p>] [--type <t>] [--value <v>]  # Update a task
```

### Groups
```bash
tc groups list                                           # List registered groups and their JIDs
tc groups register --jid <jid> --name <name> --folder <folder> --trigger <trigger>
tc groups settings [--requires-trigger true|false]  # Limit responses to @mentions only (true) or respond to all messages (false)
```

### Runtime
```bash
tc runtime prune <scope>    # Prune runtime — scope: builder|images|volumes|all
tc runtime disk             # Show disk usage breakdown
tc runtime reset-buildkit   # Reset buildkit daemon (use when builds are corrupted)
```

**Prune scopes** (safe scopes only — `images-all` is blocked for agents):
- `builder` — clears buildkit build cache (safe, recommended for freeing disk)
- `images` — removes dangling (untagged) images only (safe)
- `volumes` — removes unused volumes (caution: deletes app data volumes not in use)
- `all` — removes stopped containers + dangling images (safe if apps are running)

Do NOT use `images-all` via tc — it removes ALL unused images including app images, breaking app restarts.

### Proxy
```bash
tc proxy                    # Show residential SOCKS5 proxy URL (if available for this tenant)
```

If a proxy URL is returned, pass it to agent-browser: `agent-browser --proxy <url> "..."` or use it with any SOCKS5-capable HTTP client. Useful when sites block datacenter IPs (travel booking, hotel search, etc.).

### Credentials

**Always use `tc creds` to store secrets, API keys, tokens, and passwords. Never write sensitive values to USER.md, MEMORY.md, plain text files, or environment variable files.**

```bash
tc creds set <name> <value>         # Store or update a credential (encrypted at rest)
tc creds                            # List stored credential names
tc creds get <name>                 # Get a credential value
```

When a user asks you to remember, save, or store an API key, token, password, or any other secret — always use `tc creds set`, not USER.md or any file.

## Using the SDK programmatically

Import `@treehouse/sdk` in Node.js code:

```typescript
import {
  getContext,
  // Apps
  deployApp, removeApp, stopApp, restartApp, execInApp, getAppLogs,
  listAppVolumes, removeAppVolume,
  // Status
  getHostingInfo, getAppStatus, getDeployErrors, waitForDeploy,
  // Messaging
  sendMessage, sendFile, sendVoice,
  // Tasks
  listTasks, scheduleTask, pauseTask, resumeTask, cancelTask, updateTask,
  // Groups
  registerGroup, updateGroupSettings,
  // Runtime
  pruneRuntime, getDiskUsage, resetBuildkit,
  // Credentials
  getCredential, listCredentials,
  // Proxy
  getProxyInfo,
  // LCM memory search
  lcmSearch,         // keyword/FTS search
  lcmSemanticSearch, // pure semantic/embedding search
  lcmHybridSearch,   // hybrid RRF (default — use this)
  lcmDescribe,
} from '@treehouse/sdk';

const ctx = getContext(); // { tenantId, ipcDir, workspaceDir }
await sendMessage('Hello from my app!');
await deployApp('myapp');
```

Add to `package.json`:
```json
{
  "dependencies": {
    "@treehouse/sdk": "file:/opt/treehouse/sdk"
  }
}
```

## Notes

- `tc app restart`, `tc app exec`, `tc app logs`, `tc app volumes`, `tc app wait`, `tc runtime prune`, `tc runtime disk`, and `tc runtime reset-buildkit` are **blocking** — they wait for the operation to complete and print the result inline
- `tc app remove <app>` and `tc app stop <app>` resolve the app on the host side by registered name/subdomain; you do not need to know the low-level runtime service name
- `tc` and `@treehouse/sdk` are mounted read-only at `/opt/treehouse/sdk` — no installation needed in agent containers
- `TENANT_ID`, `NANOCLAW_GROUP_FOLDER`, and `NANOCLAW_CHAT_JID` are always set in agent containers
- SDK updates are available immediately in new agent sessions without an image rebuild
- For tenant app containers, opt in with `sdk: true` in `app.yml` — see the `treehouse-app-hosting` skill


## Hooks — Calling the Agent via HTTP

For integrating apps via the hooks HTTP API (`/hooks/invoke`, `/hooks/stream`, `/hooks/agent`, etc.), use the `treehouse-hooks` skill — it covers all endpoints, session/keepAlive semantics, attachments, and limits.

Get your token: `tc hooks` — enable if needed: `tc hooks enable`.

## Bug Reporting

```bash
tc report <text>    # Send a bug report to the platform admin
```

Sends a report to the platform admin channel. Use when something is broken or behaving unexpectedly and the user wants to notify the platform operator.

In the SDK:
```typescript
import { sendReport } from '@treehouse/sdk';
await sendReport('The deploy button is not working after the latest update.');
```

## Maintenance

- **After adding or modifying any tc — Treehouse CLI

Commands:
  tc whoami                               Show current tenant ID

  tc app deploy <app> [--force-rebuild]          Deploy an app (--force-rebuild forces full image rebuild)
  tc app remove <app>                     Remove an app
  tc app stop <app>                       Stop an app
  tc app restart <app> [--service <svc>]  Restart an app
  tc app logs <app> <svc> [--tail N]      Fetch app logs
  tc app exec <app> <svc> -- <cmd...>     Exec in app container
  tc app volumes <app>                    List app volumes
  tc app volumes remove <app> <vol>       Remove a named volume
  tc app wait <app> [--timeout N]         Wait for deploy to complete
  tc app status [<app>]                   Show app deploy status
  tc app errors [--limit N]              Show recent deploy errors

  tc proxy                                Show residential proxy URL (if available)

  tc hosting info                         Show hosting info

  tc send <text>                          Send a message to the current group
  tc send --group <jid> <text>            Send a message to a specific group by JID
  tc send file <path> [--caption <t>]     Send a file
  tc send voice <text>                    Send a voice message

  tc tasks                                List scheduled tasks
  tc tasks schedule --type T --value V P  Schedule a task
  tc tasks pause <id>                     Pause a task
  tc tasks resume <id>                    Resume a task
  tc tasks cancel <id>                    Cancel a task
  tc tasks update <id> [opts]             Update a task

  tc groups list                                               List registered groups and their JIDs
  tc groups register --jid J --name N --folder F --trigger T  Register group
  tc groups settings                                           Show current group settings
  tc groups settings --requires-trigger true|false            Update requires-trigger setting

  tc runtime prune <scope>                Prune runtime (builder|images|volumes|all) — NOT images-all (admin-only)
  tc runtime disk                         Show disk usage
  tc runtime reset-buildkit               Reset buildkit

  tc hooks [status]                       Show hooks token and enabled state
  tc hooks enable                         Enable hooks (auto-generates token)
  tc hooks disable                        Disable hooks
  tc hooks rotate                         Rotate the hooks bearer token

  tc report <text>                        Send a bug report to the platform admin

  tc creds [list]                         List credentials
  tc creds get <name>                     Get credential value
  tc creds set <name> <value>             Set or update a credential

## Maintenance

- **After adding or modifying any `tc` command or `@treehouse/sdk` export, update this SKILL.md** so agents have accurate documentation.
- The tc source lives in the Treehouse SDK repo. After building and deploying changes, update the commands/SDK reference sections above.
