> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truffle.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Truffile CLI

> The complete guide to using the truffile CLI — device connection, Convo, inference, app management, and more

## Overview

The `truffile` CLI is your interface to Truffle. Use it to discover and connect to devices, use Convo with the on-device agent, run raw model inference, and deploy apps.

```bash theme={null}
pip install truffile
```

Running `truffile` with no arguments opens the [Convo REPL](#convo-mode) in an
unsent side-thread draft.

***

## Scriptable commands

Most workflows can be driven with explicit arguments, which makes them easy to
test in CI or from another agent:

```bash theme={null}
truffile connect truffle-6272 --user-id "$TRUFFLE_USER_ID"
truffile list devices
truffile list apps --json
truffile load all
truffile create my-app --path ./apps
truffile validate ./apps/my-app
truffile deploy ./apps/my-app --dry-run --json
truffile deploy ./apps/my-app --json --non-interactive --replace
truffile delete my-app
truffile convo --new --json --quiet --timeout 60 "Summarize my installed apps"
truffile infer "Say pong" --json --no-stream --quiet
truffile infer --list-models --json
```

Interactive commands still exist for normal human use. Prefer the explicit
forms above when you are writing tests, scripts, or agent tools.

***

## Connecting to Your Truffle

You need to connect to a device before you can use Convo, run inference, or manage apps.

### Scan for devices

```bash theme={null}
truffile scan
```

```
✓ Scanning for Truffle devices (5s)

Found 3 Truffle device(s):

  1. truffle-6070 (192.168.1.109)
  2. truffle-5970 (192.168.1.104) [connected]
  3. truffle-6272 (192.168.1.32)

Select device to connect (1-3) or press Enter to cancel:
```

Select a device by number to start the connection flow.

### Connect directly

If you already know your device name:

```bash theme={null}
truffile connect truffle-6272 --user-id "$TRUFFLE_USER_ID"
```

If you omit `--user-id`, you'll be prompted for your **User ID** (found in **Symphony > Settings**), then asked to approve the connection on your device.

Credentials are saved locally — subsequent connections are automatic.

<Note>
  Before `truffile connect`, onboard the device in the Symphony desktop client. Download Symphony from [the client overview](/client/overview), finish device onboarding there, copy your User ID from **Symphony > Settings**, then approve the session on your Truffle when the CLI asks.
</Note>

***

## Loading agent resources

`truffile` ships with agent-readable skills and example apps. Copy them into
your current workspace when you want a coding agent to inspect them directly:

```bash theme={null}
truffile load all
```

This creates:

```text theme={null}
./truffile/
  skills/
  examples/
```

Use narrower forms when needed:

```bash theme={null}
truffile load skills
truffile load examples
truffile load all --force
truffile load all --json
```

The copied skills cover CLI usage, one-shot Convo, raw inference, and app
creation. The examples are real bundled apps that show foreground tools,
background workers, text auth, OAuth, no-auth apps, and local bridge patterns.

### Disconnect

```bash theme={null}
# disconnect from a specific device
truffile disconnect truffle-6272

# disconnect from all devices and clear all saved credentials
truffile disconnect all
```

<Warning>
  `disconnect all` clears all saved credentials. You'll need to go through the full approval flow again next time.
</Warning>

***

## Convo Mode

Convo connects to the authenticated user's stateful on-device agent. Main is
thread `0`; user conversations otherwise live in side threads. Legacy Task
histories are not migrated or listed after the one-way cutover.

```bash theme={null}
truffile convo
```

This is also the default. A bare launch starts in an unsent side-thread draft,
and the first send creates that thread. Use `/new` for another draft or
`/main` to opt into Main explicitly.

### Sending messages

Type your message and press **Enter** to send. Use **Alt+Enter** for multi-line input.

```
you> What can you help me with?

thinking: considering user's question about capabilities...
• tool: get_system_info — checking available apps

I can help you with several things...
```

Responses stream in real-time with a thinking orb animation while the model reasons. Tool calls appear inline above the response.

### Threads and history

Use `/threads` to list and switch among user-visible threads. System and
Bulletin threads are omitted. Messages and replies remain in the selected
thread, and `/history` shows its durable history.

Type `/help` inside Convo to see all commands.

| Command               | What it does                                                                             |
| --------------------- | ---------------------------------------------------------------------------------------- |
| `/threads`            | Pick from visible Convo threads                                                          |
| `/new`                | Start an unsent side-thread draft                                                        |
| `/main`               | Explicitly select Main                                                                   |
| `/history`            | Show the selected thread's history                                                       |
| `/title`              | Show the selected thread's title                                                         |
| `/rename <name>`      | Rename the selected thread                                                               |
| `/interrupt`          | Interrupt work in the selected thread                                                    |
| `/hide [name\|id]`    | Locally hide a side thread                                                               |
| `/restore [name\|id]` | Restore a locally hidden thread                                                          |
| `/deploy <path>`      | Deploy an app to the device from within Convo                                            |
| `/delete app [name]`  | Delete an installed app (interactive picker if no name given)                            |
| `/delete task`        | Compatibility alias that locally hides a side thread; reversible and not server deletion |
| `/create <name>`      | Scaffold a new app                                                                       |
| `/devices`            | List connected devices                                                                   |

`/tasks`, `/resume`, and `/switch` are temporary compatibility spellings for
the Convo thread picker. They do not access the retired Task backend.

### Installed apps

Inspect installed apps with either discovery-only command:

```bash theme={null}
truffile list apps
truffile convo --list-apps
```

Convo has no per-chat app allowlist: no app is attached to or restricted for a
thread. Interactive `/apps`, `--app`, and dynamic `/<app>` sends are
unavailable. The agent can still discover installed tools and decide whether
to use them through normal routing.

For all targeting, listing, action, JSON, and exit-code details, see
[Convo automation](/sdk/convo-automation). For the complete interactive model,
see [Convo](/sdk/convo).

#### Exiting

| Command    | What it does |
| ---------- | ------------ |
| `/exit`    | Exit Convo   |
| `/quit`    | Exit Convo   |
| **Ctrl+D** | Exit Convo   |

***

## Infer Mode

Infer mode gives you direct access to model inference with full control over generation parameters, MCP tool integration, and image input.

```bash theme={null}
truffile infer
```

### CLI flags

| Flag              | What it does                                       |
| ----------------- | -------------------------------------------------- |
| `--model <name>`  | Pre-select a model                                 |
| `--system <text>` | Set an initial system prompt                       |
| `--no-stream`     | Disable streaming (get the full response at once)  |
| `--no-tools`      | Disable built-in tools (`web_search`, `web_fetch`) |
| `--mcp <url>`     | Connect an MCP server at startup (can be repeated) |

```bash theme={null}
# start with a specific model and system prompt
truffile infer --model my-model --system "You are a helpful coding assistant"

# start with MCP server pre-connected
truffile infer --mcp http://127.0.0.1:8000/mcp
```

### Generation controls

All settings can be viewed and changed live inside the REPL. Run the command without an argument to see the current value.

| Command                     | What it does                                      | Default |
| --------------------------- | ------------------------------------------------- | ------- |
| `/reasoning on\|off`        | Show model reasoning/thinking                     | `on`    |
| `/stream on\|off`           | Stream tokens as they're generated                | `on`    |
| `/json on\|off`             | JSON response mode                                | `off`   |
| `/tools on\|off`            | Enable built-in tools (`web_search`, `web_fetch`) | `on`    |
| `/max_tokens <int>`         | Max output tokens                                 | `2048`  |
| `/temperature <float\|off>` | Sampling temperature                              | `None`  |
| `/top_p <float\|off>`       | Top-p (nucleus) sampling                          | `None`  |
| `/max_rounds <int>`         | Max tool call rounds per turn                     | `8`     |
| `/system <text\|off>`       | Set or clear the system prompt                    | `None`  |

```
> /config
chat config
  model: llama-3.1-8b
  reasoning: True
  stream: True
  json: False
  tools: True
  max_tokens: 2048
  temperature: None
  top_p: None
  max_rounds: 8
  system: <none>
  mcp: <disconnected>
```

### Built-in tools

When tools are enabled (`/tools on`, the default), the model can use:

* **`web_search`** — search the web and return top results
* **`web_fetch`** — fetch a URL and extract readable text

Tool calls are displayed inline:

```
> What's the latest news about SpaceX?

🔨 tool web_search
🔨 tool web_fetch

Here's what I found...

---
tokens [142/580/722] | decode 48.2 t/s | ttft 312ms
```

Token usage stats are printed after each response.

### Image attachments

Attach an image to your next message with `/attach`:

```
> /attach ./screenshot.png
✓ attachment ready: path=/Users/me/screenshot.png size=142.3 KiB mime=image/png

> What's in this image?
[attach] sending with image: path=/Users/me/screenshot.png size=142.3 KiB mime=image/png

The image shows...
```

You can also attach from a URL:

```
> /attach https://example.com/photo.jpg
✓ attachment ready: url=https://example.com/photo.jpg size=89.1 KiB mime=image/jpeg
```

The attachment is sent with the next message, then cleared automatically.

Supported formats: **JPEG**, **PNG**, **BMP** natively. Other formats (WebP, TIFF, etc.) are transcoded via Pillow if installed.

### MCP integration

Connect external [MCP](https://modelcontextprotocol.io) servers to give the model additional tools. Only **streamable HTTP** transport is supported.

| Command              | What it does                               |
| -------------------- | ------------------------------------------ |
| `/mcp status`        | Show connection status and tool count      |
| `/mcp connect <url>` | Connect to an MCP server                   |
| `/mcp tools`         | List available tools from connected server |
| `/mcp disconnect`    | Disconnect the MCP session                 |

```
> /mcp connect http://127.0.0.1:8000/mcp
/mcp connect ✓ http://127.0.0.1:8000/mcp (5 tools)

> /mcp tools
/mcp tools get_markets, get_market, get_orderbook, create_order, cancel_order
```

MCP tools and built-in tools work together — the model picks the right tool for each request.

<Tip>
  This is a great way to **test your app's MCP server locally** before deploying to the device. Start your MCP server, connect it via `/mcp connect`, and test with real prompts.
</Tip>

### Conversation management

| Command          | What it does                                       |
| ---------------- | -------------------------------------------------- |
| `/history`       | Show conversation history (role + content summary) |
| `/reset`         | Clear conversation history and pending attachments |
| `/models`        | Open the interactive model picker                  |
| `/config`        | Show all current settings                          |
| `/create <name>` | Scaffold a new app                                 |
| `/exit`          | Exit infer                                         |

***

## Keyboard Shortcuts

These work in both Convo and Infer modes.

| Key           | What it does                                                |
| ------------- | ----------------------------------------------------------- |
| **Enter**     | Send message                                                |
| **Alt+Enter** | Insert a new line (multi-line input)                        |
| **Tab**       | Autocomplete slash commands                                 |
| **Esc**       | Interrupt a streaming response                              |
| **Ctrl+C**    | Interrupt current operation (press twice within 3s to exit) |
| **Ctrl+D**    | Exit the REPL                                               |

***

## App Management

### Create a new app

```bash theme={null}
# interactive — prompts for name
truffile create

# with a name
truffile create my-app

# in a specific directory
truffile create my-app --path ./apps
```

Creates a scaffold with `truffile.yaml`, foreground/background entry points, and a default icon.

### Validate an app

```bash theme={null}
truffile validate ./my-app
```

Checks your `truffile.yaml` configuration and Python file syntax.

### Deploy an app

```bash theme={null}
# deploy from current directory
truffile deploy

# deploy from a path
truffile deploy ./my-app

# dry run — show the deploy plan without touching the device
truffile deploy --dry-run

# interactive mode — opens a terminal inside the app container
truffile deploy --interactive
```

The deploy process:

1. Validates `truffile.yaml` and Python syntax
2. Resolves app shape (foreground, background, or both)
3. Uploads files and runs installation steps
4. Registers the app with the device

`oauth` steps print an authorization URL and ask for the pasted callback URL or code. `welcome` steps print their content and wait for Enter. `vnc` / browser setup steps are rejected by validation and should be installed through Symphony Settings.

<Tip>
  Use `truffile deploy --interactive` to open a shell inside your app's container. Useful for debugging, installing extra dependencies, or testing your app manually before finalizing.
</Tip>

### List apps and devices

```bash theme={null}
truffile list apps      # installed apps on the connected device
truffile list devices   # devices you have saved credentials for
```

### Delete apps

```bash theme={null}
# interactive picker
truffile delete

# delete all apps
truffile delete all

# delete by index (1-based, as shown in the app list)
truffile delete 1 2 3

# comma-separated works too
truffile delete 1,3,5

# pipe selection
echo "all" | truffile delete
echo "1 2" | truffile delete
```

If you pass indices that are out of range or invalid, the CLI falls back to the interactive picker (when running in a terminal).

### List models

```bash theme={null}
truffile models
```

Shows all inference models available on the connected device.

***

## Convo vs Infer

Both modes let you talk to models on your Truffle, but they serve different purposes:

|                        | Convo                                                             | Infer                                                        |
| ---------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------ |
| **What it is**         | Stateful agent over Main and side threads                         | Direct model inference REPL                                  |
| **Command**            | `truffile convo` (or just `truffile`)                             | `truffile infer`                                             |
| **Conversations**      | Durable Convo threads                                             | In-memory history, cleared on exit                           |
| **Apps**               | Agent can discover installed tools; no per-thread app restriction | No app integration                                           |
| **MCP**                | No MCP (apps provide tools)                                       | Full MCP support via `/mcp connect`                          |
| **Image input**        | Not available                                                     | `/attach <path-or-url>`                                      |
| **Generation control** | Managed by the agent                                              | Full control (`/reasoning`, `/stream`, `/temperature`, etc.) |
| **Built-in tools**     | Agent decides tool use                                            | `web_search` + `web_fetch` (toggleable)                      |
| **Best for**           | Using your Truffle day-to-day                                     | Testing models, MCP servers, and prompts                     |

***

## Command Reference

| Command                                                                                                                  | Description                                            |
| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
| `truffile`                                                                                                               | Start Convo in an unsent side-thread draft (default)   |
| `truffile scan`                                                                                                          | Scan network for Truffle devices                       |
| `truffile connect <device>`                                                                                              | Connect to a device                                    |
| `truffile disconnect [device\|all]`                                                                                      | Disconnect and clear credentials                       |
| `truffile create [name] [--path <dir>]`                                                                                  | Scaffold a new app                                     |
| `truffile validate [path]`                                                                                               | Validate app config and sources                        |
| `truffile deploy [path]`                                                                                                 | Deploy app to connected device                         |
| `truffile deploy --dry-run`                                                                                              | Show deploy plan without changes                       |
| `truffile deploy --interactive`                                                                                          | Deploy with interactive terminal                       |
| `truffile list apps`                                                                                                     | List installed apps                                    |
| `truffile list devices`                                                                                                  | List connected devices                                 |
| `truffile delete [all\|1 2 3]`                                                                                           | Delete apps (interactive, by index, or all)            |
| `truffile models`                                                                                                        | List models on connected device                        |
| `truffile convo [PROMPT...] [--prompt-file FILE\|--stdin] [--main\|--thread NAME\|--thread-id ID\|--resume-last\|--new]` | Open the Convo REPL or send a targeted one-shot prompt |
| `truffile convo [--rename NAME\|--history\|--interrupt\|--hide THREAD\|--restore THREAD] [--include-hidden]`             | Act on Convo threads                                   |
| `truffile convo [--list-chats [N]\|--list-threads [N]\|--list-apps] [--json]`                                            | List Convo threads or installed apps                   |
| `truffile infer [--model M] [--system S]`                                                                                | Raw inference REPL                                     |
| `truffile help`                                                                                                          | Show help                                              |