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.

pip install truffile

Running truffile with no arguments opens the Convo REPL 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:

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

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:

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.

Before truffile connect, onboard the device in the Symphony desktop client. Download Symphony from the client overview, finish device onboarding there, copy your User ID from Symphony > Settings, then approve the session on your Truffle when the CLI asks.

---

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:

truffile load all

This creates:

./truffile/
  skills/
  examples/

Use narrower forms when needed:

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

# disconnect from a specific device
truffile disconnect truffle-6272

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

disconnect all clears all saved credentials. You’ll need to go through the full approval flow again next time.

---

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.

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:

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. For the complete interactive model, see 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.

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)

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

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.

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

# 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

truffile validate ./my-app

Checks your truffile.yaml configuration and Python file syntax.

Deploy an app

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

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.

List apps and devices

truffile list apps      # installed apps on the connected device
truffile list devices   # devices you have saved credentials for

Delete apps

# 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

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