CLI

The Peers CLI (peers) lets you interact with the Peers app entirely from the terminal. You can chat with assistants, query databases, run tools, tail logs, inspect directly connected devices, grant local folders, and control the UI — all without opening the app window.

The CLI communicates with a running Peers host (the desktop app or peers-headless) over a local WebSocket connection. If the desktop app isn't running and you have not passed --auth-file, the CLI starts Electron automatically.

Installation

The CLI is installed automatically with the Peers desktop app. After installing Peers, the peers command is available in your terminal.

Verify it's working:

peers --version

Quick start

# Chat with the built-in assistant
peers "What tasks do I have?"

# Start an interactive chat session
peers

# List all database tables
peers db tables

# List available tools
peers tools list

# Check app status
peers app status

# List directly connected devices
peers devices

# Invite a contact / see pending invites
peers contacts invite
peers invites

# Talk to a peers-headless process instead of Electron
peers --auth-file ~/peers/cli/headless-auth.json db tables

--auth-file (or PEERS_CLI_AUTH_FILE) points the CLI at any host that wrote an auth JSON. When that flag is set, the CLI will not auto-start Electron.

Commands

Messaging

Send a message to the assistant and get a response:

peers "your message here"

For an interactive session with conversation history, start the REPL:

peers

REPL commands:

• /clear — start a new thread
• /exit or /quit — exit the REPL

Options:

Flag	Description
-v, --verbose	Show detailed progress output
-c, --context <id>	Data context: a groupId, or personal (default)

peers db — Database

Query the local SQLite database, or a directly connected device's database, with read-only SELECT and approved introspection PRAGMA statements.

note

Database access must be enabled in the app: Help → Enable CLI Database Access

Remote queries also require a verified direct connection. The target device independently authorizes the connected user with exact TrustLevel.Self; the CLI cannot bypass that check.

# List all tables
peers db tables

# Query a table (first 20 rows)
peers db Users

# Query with a row limit
peers db Tasks -n 100

# Run a custom SQL query
peers db query "SELECT * FROM Users WHERE name LIKE '%mark%'"

# Inspect table structure
peers db query "PRAGMA table_info(Users)"

# Output as JSON for piping
peers db tables --json | jq

# Query a directly connected device
peers db query "SELECT * FROM PersistentVars" --device <deviceId> --json

Options:

Flag	Description
-n, --limit <count>	Maximum rows to return (default: 20)
--json	Output as JSON (one object per line)
-c, --context <id>	Data context: a groupId, or personal (default)
--device <id>	Query a directly connected device instead of the local desktop

Remote results are capped at 500 rows and 1 MB. The result indicates when that provider-side limit truncated the response. Human output marks the row or table summary as truncated. With --json, stdout remains row-oriented JSON and the truncation warning is written to stderr.

peers devices — Direct connections

List the local desktop's verified and unverified direct device connections:

peers devices
peers devices --json

Each verified row also says encrypted when the per-frame cipher is armed on that connection, or legacy when the remote runs a build without it (see Devices); --json exposes the same fact as frameCipherArmed.

Inspect the portable administration capabilities and enforced limits advertised by one target:

peers devices status <deviceId>

Only direct connections are listed. A device that is merely known through synchronized records or an indirect network path is not available to --device.

peers pair — Add a new device

Approve a new device that is showing a pairing code, from a signed-in host. The host the CLI is connected to (Electron by default, or a headless host via --auth-file) is the signed-in side; its account credentials are sent to the new device once the code checks out.

peers pair 7-guitar-revenge-tunnel      # prompts before sending credentials
peers devices pair 7-guitar-revenge-tunnel
peers pair 7 guitar revenge tunnel -y   # approve without the prompt
peers pair status                       # current ceremony state
peers pair cancel                       # abandon the active ceremony

peers devices pair is the same command as peers pair. --json prints each state transition as a JSON line (connecting, waiting-for-approval with the new device's name, transferring, complete). The command exits non-zero if the code is wrong, the ceremony is rejected, or it fails. See Add another device for the ceremony and Headless host for pairing a headless process as the new device.

peers tools — Tools

List, inspect, and execute tools.

# List all tools
peers tools list

# Show tool details and schema
peers tools get "new-task"

# Run a tool with JSON input
peers tools run "new-task" '{"title": "Buy groceries", "status": "Queued"}'

# Run a tool in a group context
peers tools run "add-to-shopping-list" '{"item": "milk"}' -c <groupId>

# Inspect and run tools on a directly connected device
peers tools list --device <deviceId>
peers tools run "new-task" '{"title": "Remote task"}' --device <deviceId>

Tool lookup supports exact ID, exact name, and fuzzy text search. If a fuzzy search matches multiple tools, you'll be prompted to use a more specific name or the tool ID.

Options:

Flag	Description
--json	Output as JSON
-c, --context <id>	Data context: a groupId, or personal (default)
-a, --assistant <id>	Assistant ID to use as context for the tool run
-n, --limit <count>	Max tools to list (default: 100)
--device <id>	Query or run tools on a directly connected device

peers logs — Logs

Query and tail console logs from the app.

# Show last 50 logs
peers logs

# Follow logs in real-time (like tail -f)
peers logs -f

# Show only errors
peers logs -e

# Show warnings and errors
peers logs -l warn,error

# Logs from the last 5 minutes
peers logs --since 5

# Search log messages
peers logs -q "database" --full

# Filter by process
peers logs -p main

# Output as JSON for processing
peers logs --json | jq

# Read or follow a directly connected device's logs
peers logs --device <deviceId>
peers logs --device <deviceId> -f

Options:

Flag	Description
-f, --follow	Follow mode — continuously show new logs
-l, --level <levels>	Filter by log level(s), comma-separated: debug, info, log, warn, error
-e, --error	Shorthand for --level error
-w, --warn	Shorthand for --level warn,error
-p, --process <name>	Filter by process name (main, renderer, worker)
-s, --source <source>	Filter by source file/module
-q, --search <text>	Search in log messages
--since <minutes>	Show logs from last N minutes
-n, --limit <count>	Maximum logs to show (default: 50)
--full	Show full context objects and stack traces
--json	Output as JSON (one object per line)
-c, --context <id>	Data context on the target; personal by default
--device <id>	Query a directly connected device

Follow mode polls serially and reports polling failures on stderr. A successful poll resets the failure count; three consecutive failures stop the command with a nonzero exit instead of leaving a disconnected or unauthorized session running silently. In --json mode, stdout remains newline-delimited log records.

peers contacts, peers groups, peers invites — Invites

Issue, accept, and review invites from the terminal. These commands talk to the running app's System Invites contract, so they act as the signed-in user and share the same pending list as the UI.

# Contacts
peers contacts                          # list contacts
peers contacts invite                   # one-off contact invite (link + token)
peers contacts invite --profile         # reusable profile invite (QR payload)
peers contacts accept <token|link>      # accept a contact invite
peers contacts pending                  # pending contact invites, in and out

# Groups
peers groups                            # list my groups
peers groups invite <groupId> <userId>  # invite an existing contact directly
peers groups invite <groupId> --link    # shareable link (approve each join)
peers groups invite <groupId> --link --mode open --expires 24h
peers groups join <token|link>          # join a group from a link
peers groups pending                    # pending group invites and join requests

# Everything pending
peers invites                           # show pending invites
peers invites preview <token>           # verify a token and show what it grants
peers invites accept <inviteId|token>
peers invites decline <inviteId>
peers invites approve <inviteId> [--role admin]
peers invites deny <inviteId>
peers invites revoke <inviteId>
peers invites sync                      # fetch mailbox, retry queued sends
peers invites regenerate-profile        # revoke all my tokens, issue a new profile QR

Options:

Flag	Description
--role <role>	reader, writer, admin, owner, or a number. Default writer for invites
--mode <mode>	Link mode: approve (default) or open (auto-admit)
--uses <n>	Link uses: 1 or unlimited (default)
--expires <duration>	Lifetime such as 30m, 12h, 7d
--trust <level>	Trust level for a new contact when accepting
--status <status>	peers invites list filter: pending, accepted, declined, expired, revoked, used
--direction <dir>	peers invites list filter: in or out
--json	Output JSON

Tokens are accepted in any of their forms: the raw code, the https://peers.app/i#… link, or the peers://i#… deep link.

peers app — App control

Start, stop, and check the status of the Peers desktop app.

# Check if the app is running
peers app status

# Start the app
peers app start

# Restart the app
peers app restart

# Quit the app
peers app quit

# Start the development build
peers app start --dev

# Set a custom dev path
peers app config --dev-path ~/peers-app/peers-electron

Options:

Flag	Description
-d, --dev	Use development version instead of production
--dev-path <path>	Set the path to the peers-electron dev directory
--prod-path <path>	Set the path to the production app

peers ui — UI control

Control and inspect the app's UI programmatically.

# Reload the UI
peers ui reload

# Hard reload (ignore cache)
peers ui reload --no-cache

# Inspect current UI state
peers ui inspect

# Get UI state as JSON
peers ui inspect --json

# List interactive elements
peers ui inspect --elements

# Get visible text
peers ui inspect --text

# Click an element by CSS selector
peers ui click "#submit-btn"

# Set an input value
peers ui set "#search" "hello world"

# Set value, clear first, and press Enter
peers ui set "#chat-input" "hello" --clear --enter

# Scroll down
peers ui scroll --direction down

# Scroll up by 500px
peers ui scroll --direction up --amount 500

peers fs — Local folders

Grant and use directories on this device through System Local Folders. The same commands work against the desktop app and against headless (--auth-file).

# Operator grant (readwrite). groupId is a peer id.
peers fs grant ~/Documents/notes --group <groupId>

# Package-scoped read-only grant
peers fs grant ~/Documents/notes --group <groupId> --package <packageId> --mode read

peers fs grants
peers fs revoke <grantId>
peers fs ls <grantId> docs -r
peers fs index <grantId>
peers fs watch <grantId>

# Headless
peers --auth-file ~/peers/cli/headless-auth.json fs grants --json

index prints progress (indexed done/total) and a summary when the job finishes. It polls getJob every 1.5 seconds, so a missed jobFinished event still completes the command. watch lists the grant first, then prints changed events until Ctrl+C. --json prints JSON for any of these verbs. --mode is read or readwrite (the default).

Data contexts

By default, the CLI operates on your personal data. To work with a group's data, pass the -c flag with a group ID:

peers -c <groupId> "What are our shared tasks?"
peers db Tasks -c <groupId>
peers tools run "add-to-shopping-list" '{"item": "milk"}' -c <groupId>
peers db query "SELECT * FROM GroupMembers" -c <groupId> --device <deviceId>

For remote database, tool, and log operations, the context is resolved on the target device. Options that take values require an explicit value. In particular, a trailing --device or --device followed by another flag is an error and never falls back to local execution.

AI agent integration

The CLI makes Peers fully accessible to AI coding assistants and automation scripts. An AI agent can:

• Query data with peers db query "..." and get structured JSON with --json
• Discover direct targets with peers devices and add --device <deviceId> to remote operations
• Run tools with peers tools run to create tasks, set timers, or trigger workflows
• Chat with the built-in assistant via peers "..."
• Inspect and interact with the UI via peers ui
• Tail logs for debugging with peers logs -f

Architecture

The CLI connects to the running Peers desktop app via a local WebSocket (Socket.IO). On first launch, the app writes an auth token to ~/peers/cli/cli-auth.json that the CLI uses to authenticate. Local operations use the desktop RPC layer. Remote operations use that desktop as a headless bridge to a versioned System Device Operations or System Logs contract over an existing verified device connection.

The remote contract surface is deliberately portable: status, bounded read-only SQL, tool listing/lookup/execution, and logs. It does not expose arbitrary shell, filesystem, UI, process-lifecycle, or unrestricted table access. Every target call is authorized from the connection-authenticated identity and requires exact TrustLevel.Self in the target's personal context.

Configuration is stored at ~/peers/cli-config.json.

Related topics

• System: Tools — defining and using tools that the CLI can execute.
• System: Workflows — workflows triggered by CLI messages.
• System: Assistants — the assistants that respond to CLI messages.
• System: Tables — the data model behind peers db.
• System: Invites — the invite model behind peers contacts, peers groups, and peers invites.