Manual

Command Line Options

Commands match the groups shown in tiles help: Getting Started, Accounts, Sync, System, and Tools.

Getting Started

Main command (tiles)

Launches onboarding (first run) and the interactive chat.

tiles   # Onboarding (if needed) and interactive chat

Run models (tiles run)

Run a Modelfile (uses the default model if none is provided).

tiles run [MODELFILE_PATH]   # Default model if path omitted

The same optional flags below also apply when you run tiles without a subcommand.

tiles run
tiles run ./path/to/Modelfile

Optional tuning flags:

tiles run --context-length 8192
tiles run --gpu-layers 32
tiles run --offload-kqv
tiles run --offload-kqv false
tiles run --batch-size 512

--context-length <CONTEXT_LENGTH>: Context window for local inference.

--gpu-layers <GPU_LAYERS>: Number of model layers to offload to the GPU.

--offload-kqv [<OFFLOAD_KQV>]: Offload K/Q/V attention operations (true or false).

--batch-size <BATCH_SIZE>: Prompt processing batch size.

Values you set on the command line are persisted in config.toml and apply on later runs.

Create a new Modelfile by adding a plain text file named Modelfile:

FROM mlx-community/Qwen3.5-4B-MLX-4bit
SYSTEM You are Mario from Super Mario Bros, acting as an assistant.

Use any mlx-community/ model (macOS) or GGUF model (Linux) hosted on Hugging Face in the FROM field. We are working on adding more model path sources in FROM, including local paths. Learn more in the Tilekit Modelfile reference.

Help (tiles help)

Show the top-level help menu or help for a specific command.

tiles help
tiles help run
tiles help link
tiles help plugin

Accounts

Account (tiles account)

Manage your user account: root identity and display nickname.

tiles account create [<nickname>]       # Create root identity (nickname optional)
tiles account set-nickname <nickname> # Set nickname
tiles account                         # Show account details

tiles account create alice
tiles account set-nickname alice
tiles account

ATproto (tiles at)

ATproto-related commands. ATproto is currently used to share chat sessions.

• tiles at login <handle>: log in with your ATproto handle (for example, alice.bsky.social) via browser OAuth.
• tiles at logout: log out of the current ATproto account.

tiles at login alice.bsky.social
tiles at logout

Authentication currently uses a localhost callback (127.0.0.1:8988), and session state is stored locally in the Tiles database.

Data (tiles data)

Configure your data and storage paths.

tiles data set-path <path>   # Set data folder

tiles data set-path ~/.tiles/data

Plugins

Plugins (tiles plugin)

Install, list, and remove Tiles plugins. Plugins extend Tiles with extensions and bundled skills.

tiles plugin install <url-or-path>   # Install from a URL or local archive
tiles plugin uninstall <plugin-name>  # Remove an installed plugin
tiles plugin list                   # List installed plugins

tiles plugin install <url-or-path>: Install a plugin from a hosted URL or from a local .zip or .tar.gz file on disk. Verified Tiles plugins are listed at tiles.run/plugins.

tiles plugin uninstall <plugin-name>: Remove an installed plugin by name.

tiles plugin list: List installed plugins.

Plugin archives must be .zip or .tar.gz files, either downloaded from a URL or available on the local filesystem.

Plugin package layout

plugin_name
  - extensions
    - extension_1
      - ...
    - extension_2
      - ...
  - skills
    - skill_1
      - SKILLS.md

Plugins can bundle skills under skills/. Learn how to use Skills slash commands in chat.

Sync

Peer-to-peer sync has two steps. Link devices first (consent): one device creates a token, the other accepts it. Then sync chats between linked peers. Online and same-local-network offline linking use the same commands; Iroh handles transport, and mDNS can discover peers without internet.

Link devices (tiles link)

tiles link create <DID> # Start a link toward a peer and print a token
tiles link add <token>  # Accept the token on the other device
tiles link list-peers   # List linked peers by DID and nickname
tiles link revoke <DID> # Unlink a peer

Run tiles link create <DID> on one device, using the other device’s DID, and share the printed token out of band. On the other device, run tiles link add <token>. Online tokens are UCANs (for example, ucan:eyJ...YzQ); on the same local network without internet, the token is an eight-character alphanumeric code.

tiles link revoke <DID>: Unlinks a peer; their future sync requests are ignored.

Sync chats (tiles sync)

After devices are linked, one device listens while the other starts sync toward the listener’s DID.

tiles sync       # Listen for a sync request
tiles sync <DID> # Start sync with a linked peer

Run tiles sync on the receiving device. On the other device, run tiles sync <DID> (get the DID from tiles link list-peers). When a sync run finishes, both devices should show a notification.

Remote inference (tiles remote)

Share inference from one of your devices to another over Iroh. This is useful when a remote machine has the model or GPU you want, while your primary machine keeps the interactive Tiles session.

# Remote machine
tiles server start  # Starts the inference server in background
tiles remote share  # Generates an Iroh ticket
 
# Device using remote inference
tiles --remote <ticket>  # Uses remote machine inference

tiles server start starts the inference server on the remote machine before sharing it.

tiles remote share starts sharing the remote machine’s inference endpoint and prints an Iroh ticket.

tiles --remote <ticket> runs on the device intending to use remote inference, while inference happens on the remote machine.

tiles remote status   # Check remote inference sharing status
tiles remote unshare  # Stop sharing remote inference

System

App updates (tiles update)

Update Tiles to the latest version.

tiles update   # Check for and install app updates

Health (tiles health)

Check the status of dependencies.

tiles health

Inference server (tiles server)

Configure the inference server.

tiles server start            # Start the inference server
tiles server stop             # Stop the inference server
tiles server daemon true      # Keep inference running after the REPL exits
tiles server daemon false     # Stop inference when the REPL exits (default)

tiles server daemon [FLAG] configures whether inference runs in the background. FLAG is true or false. When true, closing the REPL does not stop inference. The setting is stored under [inference] daemon in config.toml.

Daemon (tiles daemon)

Configure daemon behavior.

tiles daemon start        # Start the daemon (auto-starts when you run `tiles`)
tiles daemon start 1729   # Start the daemon on a custom port
tiles daemon stop         # Stop the daemon

Slash commands

Slash commands give you fast, keyboard-first control over Tiles in interactive chat. Type /? or /help in the prompt to open available commands and quickly run actions like checking session state, resuming prior sessions, and sharing chats without leaving the terminal. Use /bye to exit the chat session.

Session Commands

/status

Show the current session state.

/sessions

List available sessions in local storage.

/resume <sessionId>

Resume a specific session by ID.

Sharing Commands

These commands require an active ATproto login. See ATproto (tiles at).

/share (via ATproto)

Create a shareable link for the current session.

/share <sessionId> (via ATproto)

Create a shareable link for a specific session.

Example shared session link: chat.tiles.run/YXQ6Ly9k…ZTJr.

Using Skills

Plugins can ship skills alongside extensions. Tiles can also use available skills automatically during a conversation when appropriate.

/skills

List available skills from installed plugins.

$<skill-name>

Run a skill directly (for example, $my-skill).

Uninstall Tiles

Use tiles uninstall to uninstall Tiles from the system.

tiles uninstall

By default, it keeps the user data folder, downloaded models, and config.toml, so chats, memory, databases, logs, local settings, and model files remain for a later reinstall.

For a complete cleanup, pass --all:

tiles uninstall --all