Skip to main content

​
Overview

The truffile CLI lets you discover, connect to, and deploy apps to your Truffle devices. 
truffile

🍄‍🟫 truffile - TruffleOS SDK

Usage: truffile <command> [options]

Commands:
  scan                      Scan network for Truffle devices
  connect <device>         Connect to a Truffle device
  disconnect <device|all>  Disconnect and clear credentials
  deploy [path]            Deploy an app (reads type from truffile.yaml)
  list <apps|devices>      List installed apps or devices
  models                    List AI models on connected device
  proxy                     Start OpenAI-compatible inference proxy

​
Connecting to Your Truffle

​
Step 1: Scan for Devices

Find Truffle devices on your local network: 
truffile scan

✓ Scanning for Truffle devices (5s)

Found 6 Truffle device(s):

  1. truffle-6070 (192.168.1.109)
  2. truffle-5970 (192.168.1.104)
  3. truffle-6272 (192.168.1.32)
  4. truffle-7280 (192.168.1.87)
  5. truffle-0148 (192.168.1.60)
  6. truffle-6239 (192.168.1.129)

Select device to connect (1-6) or press Enter to cancel:
Select a device by entering its number.

​
Step 2: Enter Your User ID

After selecting a device, you’ll be prompted for your User ID: 
✓ Resolving truffle-6272.local

  Make sure you have:
  • Onboarded with the Truffle app
  • Your User ID from the recovery codes

? Enter your User ID:
You can find your User ID in the Settings → About section of your Truffle desktop client.

​
Step 3: Approve the Connection

After entering your User ID, you’ll see: 
✓ Connecting to device

• Requesting authorization...
  Please approve on your Truffle device
⠋ Waiting for approval
A dialog will appear on your Truffle client asking you to approve the connection:
Approve connection dialog
Click Approve to allow the connection. 
✓ Waiting for approval

✓ Connected to truffle-6272

​
Reconnecting Later

Once you’ve connected to a device, you can reconnect directly without scanning: 
truffile connect truffle-6272
Your credentials are saved locally, so you won’t need to re-enter your User ID or approve again.

​
Disconnecting

To disconnect from all devices and clear your saved credentials: 
truffile disconnect all
This will require you to go through the full connection process again (User ID + approval) the next time you want to connect.
To disconnect from a specific device: 
truffile disconnect truffle-6272

​
Deploying Apps

Once connected, you can deploy apps to your Truffle.
If you haven’t built an app yet, check out the Building Apps guide first.

​
Basic Deploy

Deploy an app from the current directory: 
truffile deploy
Or specify a path to your app folder: 
truffile deploy ./my-app
truffile will:
  1. Validate your truffile.yaml configuration
  2. Check syntax for all Python files
  3. Determine if it’s an Ambient (background) or Focus (foreground) app
  4. Upload files and run installation steps
  5. Register the app with your Truffle

​
Interactive Mode

Deploy with an interactive terminal session for debugging: 
truffile deploy -i
This uploads your files and opens a terminal inside your app’s container. You can:
  • Test your app manually
  • Install additional dependencies
  • Debug issues in real-time
You can even install Claude Code inside the container to help fix or extend your app!
curl -fsSL https://claude.ai/install.sh | bash
Type exit or press Ctrl+D to finish the deploy.

​
Listing Apps & Devices

​
List Installed Apps

See all apps installed on your connected Truffle: 
truffile list apps

​
List Connected Devices

See all devices you have saved credentials for: 
truffile list devices

​
Command Reference

CommandDescription
truffileShow help menu
truffile -hShow help menu
truffile scanScan network for Truffle devices
truffile connect <device>Connect to a specific device
truffile disconnect <device>Disconnect from a specific device
truffile disconnect allDisconnect from all devices
truffile deployDeploy app from current directory
truffile deploy <path>Deploy app from specified path
truffile deploy -iDeploy with interactive terminal
truffile list appsList installed apps
truffile list devicesList connected devices
truffile modelsList AI models on device
truffile proxyStart OpenAI-compatible proxy

​
Next Steps

  • Ready to build your own apps? Check out the Building Apps guide.
  • Want to use your Truffle for AI inference? See the Inference guide.