Skip to main content

CLI

The Peers CLI (peers) lets you interact with the Peers app entirely from the terminal. You can 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. Local commands such as peers new-id do not connect to or start a host.

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​

# Generate an id without starting the app
peers new-id

# 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 that need the desktop app start it when it is not running. With --json, that startup progress goes to stderr, so stdout holds only the command's JSON.

Git remotes​

The desktop app installs git-remote-peers beside peers in ~/.local/bin, on macOS, Linux and Windows. Git finds it on PATH when a remote starts with peers://:

git clone peers://<groupId>/<repoId>

On Windows it needs Git for Windows, which runs the helper with its own sh; open a new terminal after installing so ~/.local/bin is on PATH. peers git doctor checks the setup.

Install the Git package in that context and keep the host running. The helper never starts Electron and writes only Git protocol to stdout; diagnostics go to stderr. It uses the same CLI authentication file as peers. To target a headless host:

PEERS_CLI_AUTH_FILE=/path/to/headless-auth.json git fetch peers

For peers git, select that host with --auth-file; its push and clone operations use the same host:

peers --auth-file /path/to/headless-auth.json git clone "My project" -c <groupId>

For monorepo development, build peers-cli and add peers-cli/bin to PATH. See Git for sharing a repository, personal branch names, permissions, and offline fetches.

Commands​

peers and unknown commands​

Bare peers, and peers --help, print the list of commands; peers <command> --help shows one command's options. Neither starts the app. An unknown command or option, such as peers status or peers --hlep, is an error: the CLI prints it on stderr with the help and exits with status 1, without starting the app or calling it.

peers db — Database​

Query the local SQLite database, or a directly connected device's database, with read-only statements. Locally, any single statement SQLite reports as read-only and returning rows runs: SELECT, WITH ... SELECT (recursive CTEs included), and pragmas that read, such as PRAGMA table_info(Users). Writes and pragmas that set something (PRAGMA user_version = 1) are refused. With --device, the query is limited to SELECT and an allowlist of 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)"

# Walk a tree with a recursive CTE
peers db query "WITH RECURSIVE t(id) AS (SELECT '<taskId>' UNION ALL SELECT c.taskId FROM Tasks_00mh0wlipjixk2gqmurbwee0o c JOIN t ON c.parentTaskId = t.id) SELECT count(*) FROM t"

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

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

# Database files on the device: size, free space, journal; removed groups and orphans included
peers db size
peers db size --device <deviceId>

# VACUUM every open database (or the ones named) to return free space to the disk
peers db vacuum
peers db vacuum <groupId> --device <deviceId>

peers db size and peers db vacuum use System Storage, not the database access setting. --device runs them on one of your own directly connected devices (it trusts you as Self). VACUUM rewrites a database and takes a few seconds per 100 MB. Meanwhile the desktop app pauses, and in the browser app every database waits. The free space peers db size shows counts only empty pages, so a VACUUM can get back more than that, from pages left part-filled. Peers may also vacuum a database once by itself, a few minutes after starting, when that frees a lot of space.

Options:

FlagDescription
-n, --limit <count>Maximum rows to return (default: 20)
--jsonOutput 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 once the per-frame cipher is armed on that connection (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 files — File storage​

Each account keeps its file contents in its own encrypted database on the device. Older builds kept them as plain files in one folder per device (~/peers/data/files/file_chunks on desktop, <files-dir>/file_chunks on headless), shared by every account. Each start copies the signed-in account's contents out of that folder, about half a minute after startup, until the copy is verified. Reads use the folder in the meantime, so nothing waits for it.

# How much is stored, and where the copy from the old folder stands
peers files

# Free expired files' unused contents on this device now
peers files gc

# Preview what would be freed in each context and the next deadlines
peers files gc --dry-run

# Inspect personal files, or files in a group
peers files list
peers files list -c <groupId> --json

# Continue a list using its next cursor (50 files per page by default)
peers files list -c <groupId> --after <nextCursor> --limit 100

# Rebuild file references after editing declared file fields through raw SQL
peers files reindex

# Copy now instead of waiting for the next start
peers files migrate

# Delete the old folder, once every account on this device has copied its contents
peers files remove-legacy-chunks

peers files reports the copy as pending, running, verified or blocked. A blocked copy lists why, for example a file an older build kept in a format this one can't read. The old folder stays until you remove it. remove-legacy-chunks first copies the signed-in account's contents again, picking up files that arrived since the last copy. It refuses while any account on the device hasn't copied its contents, and names those accounts: start Peers as each of them, then try again. Package bundles that no package version uses any more aren't copied, so they're freed when the folder goes. Desktop and headless only; the PWA removes its old store by itself.

Collection runs automatically, and gc requests a run now. It waits for the legacy copy to be verified and for sync to be idle; a skipped or interrupted run says why. --dry-run deletes nothing, though it can start the normal retention clock for a newly unreferenced file. See System Files for what is kept, when unused contents are freed, and how a file can be fetched again.

list shows names, sizes, references, whether contents are in this account's current store, and local expiry deadlines. A deadline is the earliest a file becomes eligible: shared or recently saved contents can stay longer. List summaries count logical file sizes, so shared contents can count more than once; peers files reports the device's actual stored total. During migration, reads can also use the old folder, which listing files does not copy from. --limit accepts 1–200 files. Collection previews likewise show each context's eligible contents, which can overlap across groups; the overall freed total counts shared contents once.

The Files tab shows the same list in a group's settings, and in Settings → Files for your personal space.

gc and reindex require Admin; list requires Reader in the selected context. These commands are for the signed-in user's UI or CLI on this device. --json works with each command. A CLI connected to an older host reports that the host does not provide the new tool; update the host to use it.

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 keys — Signing key​

Show the signing key of the account the connected host is signed in to.

peers keys                               # current key, previous keys, anchors, registry status
peers keys show --json
peers keys email bind --email you@example.com
peers keys email verify --email you@example.com --code 123456
peers keys email session --code 123456
peers keys rotate # publish through the open session; prints a document for any https anchor
peers keys rotate --manual # write nowhere: print the document, then wait for every anchor
peers keys email unbind
peers keys contest --pending <publicKey>
peers keys email session --user <userId> --code <code>
peers keys recover --user <userId>
peers keys recover --user <userId> --manual
peers keys anchors list
peers keys anchors add --url https://example.com/.well-known/peers-identity.json
peers keys anchors remove --url https://example.com/.well-known/peers-identity.json
peers --auth-file ~/peers/cli/headless-auth.json keys show

peers keys rotate publishes the new key to peers-services when a recovery-email session is open. If an https anchor is also on the account it first prints the anchor document for you to publish there, then waits. The host rotates only after every anchor on record lists the new key; if any anchor refuses or the registry rejects the write, the command exits non-zero and nothing local changes. With no anchors on record it reports Rotation needs an anchor that accepts writes. peers keys rotate --manual writes nowhere: it prints the document and waits for every anchor, including peers-services, which an operator seeds. peers keys email unbind removes the mailbox. peers keys contest --pending objects to a recovery with the key this host still holds. peers keys recover --user runs on a signed-out desktop after a recovery-email session for that user, or with --manual after an operator has published the document; a headless host is never signed out (see Headless › Recovering a lost key). Groups need a new invite, and secrets wrapped under the lost key stay unreadable. peers keys anchors add and remove publish the full list at the anchors already on record. An https anchor has to be serving that list first. A passkey, added from the account screen, opens the same session as the recovery email. See Key Registry › User key rotation and Identity › Lost your key.

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" '{"name": "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>

Local tools list [query], tools get, and direct tools run use the System Tool Catalog. Omitted -c always means your personal context. personal and me are aliases for that context.

Lookup uses exact ID, exact name, then text. Multiple distinct targets are ambiguous for both names and text; use the stable tool ID. Contract tools invoke the selected provider after schema validation. Unavailable entries print their actionable availability.message and exit 1. Unknown dispatch values ask you to update Peers. Legacy tool execution has been removed; migrate packages to contract resolvers.

The list columns are toolId, name, dispatch/reason, contract@version, and description. list --json emits one catalog entry per line; get --json emits one entry with target, availability, providers, and access. run --json prints the target result. For example, an entry contains availability: {dispatch: "contract"} and target: {contractId, version, toolName}; it is no longer a raw Tools row.

--provider and --fallback-to-default are rejected with --device. --device retains Device Operations metadata JSON and sends the original lookup query to the remote host, which runs the tool through its catalog under the caller’s own identity and role. Local-only targets cannot run remotely.

Options:

FlagDescription
--jsonOutput as JSON
-c, --context <id>Data context: a groupId, or personal (default)
-n, --limit <count>Max tools to list (default: 100)
--device <id>Query or run tools on a directly connected device
--provider <packageId>Prefer this contract provider; fail if absent
--fallback-to-defaultAllow the active provider if the preferred provider is absent

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 electron

# What a package's worker printed (privileged or sandboxed)
peers logs -p worker -s "Kube Tools"

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

FlagDescription
-f, --followFollow mode — continuously show new logs
-l, --level <levels>Filter by log level(s), comma-separated: debug, info, log, warn, error
-e, --errorShorthand for --level error
-w, --warnShorthand for --level warn,error
-p, --process <name>Filter by process: electron, ui, headless, or worker (package workers)
-s, --source <source>Filter by source: a module, or the package's name for worker lines
-q, --search <text>Search in log messages
--since <minutes>Show logs from last N minutes
-n, --limit <count>Maximum logs to show (default: 50)
--fullShow full context objects and stack traces
--jsonOutput 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.

On the desktop app, unexpected failures are logged rather than shown as a popup, so an unattended device keeps running and the cause is in its log. That covers errors nothing handled, the window's UI crashing (the app reloads it) or hanging, and the system sleeping or waking. Find them with peers logs --device <deviceId> -q "[ProcessHealth]".

The PWA logs one [Storage] line a minute after it opens: what the browser holds for it (usage and quota, split into OPFS files, IndexedDB and the service worker's cache where the browser reports that), then each open database's size and free space. Find it with peers logs --device <deviceId> -q "[Storage]". On any device you can also read one database's size with peers db query "PRAGMA page_count" --device <deviceId> -c <groupId> (times PRAGMA page_size), and its free pages with PRAGMA freelist_count. A phone's PWA is reachable only while it's open on screen.

peers contacts, peers groups, peers invites — Invites​

Manage groups and issue, accept, and review invites from the terminal. These commands act as the signed-in user in the running app and share the same pending invite 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 removed # list the groups I removed
peers groups remove <groupId> # remove a group from my groups on all my devices (other members keep it)
peers groups restore <groupId> # bring back a removed group
peers groups purge <groupId>... # list what deleting a removed group's files on this device would free
peers groups purge --all-removed --yes # delete this device's files for every removed group and orphan
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
peers groups resign <groupId> | --all # re-sign memberships (bound to each member's key), settings and packages with your key (--all: groups you founded and haven't removed)

# 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

peers groups delete <groupId> is an alias of remove. Both are reversible: they hide the group on all your devices without deleting its data or changing other members' lists. Use peers groups removed to find it and peers groups restore <groupId> to bring it back. peers groups (including --json) lists only groups you haven't removed.

peers groups purge deletes a removed group's database files, permanently, on one device: this one, or one of yours with --device <id>. Without --yes it only lists what it would delete. It also deletes orphans: files for groups that no longer have a record. It refuses a group you haven't removed. After a purge, restoring the group can only sync its data again from another member, so a group only you were in can't come back.

Options:

FlagDescription
--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
--all-removedpeers groups purge: every removed group's and orphan's files
--yespeers groups purge: delete, rather than list what would be deleted
--device <id>peers groups purge: run on one of your directly connected devices
--jsonOutput 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

# Restart another of your devices
peers app restart --device <deviceId>

# Start the development build
peers app start --dev

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

Options:

FlagDescription
-d, --devUse 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
--device <id>restart or quit another of your devices instead of this one

restart and quit call the System Host Shell contract, so they also work against a headless host (--auth-file). With --device, the target must trust you as Self and have Allow my other devices to update and restart this device turned on (see Update another device).

peers ui — UI control​

Inspect, drive, and screenshot the app's UI programmatically. These commands call the System Host Shell contract, so they need the desktop app; a headless host answers System Host Shell <tool> is not supported on this host (headless has no …).

# Reload the UI
peers ui reload

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

# Save a screenshot of the Peers window and print the file path
peers ui screenshot

# Scaled-down JPEG at a chosen path; prints {path,width,height,mimeType}
peers ui screenshot --out ~/Desktop/peers.jpg --jpeg --max-width 1280 --json

# 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

# Run any of these on another of your devices
peers ui inspect --device <deviceId>

screenshot writes to ~/peers/screenshots/peers-<timestamp>.png unless you pass --out, and prints the file path, so an agent can open that file to see the UI (for example after a reload). inspect prints a CSS selector for each element (using :nth-of-type) that click, set, and scroll --selector accept. --json also prints the result of click, set, scroll, and reload. A failed action exits 1, and an unknown action or option is an error. Scroll offsets accept negative values; use -- before literal text starting with -, for example peers ui set '#search' -- '--help'. --max-width must be a positive integer.

--device <id> runs the command on another device, which must trust you as Self. Errors name the cause:

  • Device <id> does not trust this account as Self, so it refuses UI control from another device
  • The requested data context is unavailable on device <id>. Personal calls to another account's device require a direct connection; group calls require that group on the target.
  • This Peers host does not support UI control (System Host Shell). Update Peers. from an older host, or Device <id> does not support UI control (System Host Shell). Update Peers there.

In your personal context, a --device call to a directly connected device goes over that connection and runs in the target's own personal context. That is how another account's device that trusts you as Self, such as a Kitchen hub, is reached.

peers ui and peers app accept but ignore the global -c/--context option: Host Shell commands always use the personal context. Global flags, including --auth-file, are not interpreted after --; those tokens are literal operands. A context option before -- still requires a nonempty value.

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

peers packages: Packages​

These commands list, inspect, import, reload, activate, and remove packages through the System Packages contract. They work against the desktop app and against headless (--auth-file). The default is your personal context; add -c <groupId> for a group.

peers packages                                  # name, id, running version, status
peers packages get <packageId> --json # versions, runtime state, last error
peers packages import ./my-package # relative paths resolve against this shell
peers packages import https://github.com/org/pkg.git
peers packages create "My Package" --location ~/code/my-package
peers packages reload <packageId> # exits 1 if the new version fails to load
peers packages reload --all
peers packages activate <packageId> [<packageVersionId>] [--group]
peers packages promote <packageVersionId> beta [--group] # or stable; reports what the group runs
peers packages list --device <deviceId> # run on another of your devices (Self trust)
peers packages install <packageId> --from personal -c <groupId>
peers packages uninstall <packageId>
peers packages capabilities --json

With --json, list prints one JSON object per line and every other command prints one object. A failed operation exits 1 and prints Error: <message> to stderr. After a failed reload, the previous code keeps running; get shows load errors in runtime.lastError. Changed builds at a released number are refused: bump version in package.json, rebuild, and reload. An identical release creates no dev version or device selection. Single reload restarts the selected version; reload --all leaves unchanged packages running and exits 1 if any package fails. Page refresh also checks folders and logs failures to the developer console. Import and reload also warn when the folder's SDK is newer than Peers, without failing the operation (exit 0). Reload-all identifies each affected package. Pin @peers-app/peers-sdk to the Peers version your devices run, or update Peers. See Packages.

get also lists each contract the running package uses that nothing on this device serves, as Not served here: <contractId> v<version> (with --json, runtime.running.consumes entries with satisfied: false). Calls to those fail on this device; not every host serves every system contract.

A package that requires a contract no package in the context provides is installed but waits (Waiting packages). The list shows its status as waiting for <contract> (update waiting for <contract> while an older version keeps running), and install, activate and reload succeed and say so. get prints each missing contract with the packages that provide it and the command that adds each one, for example peers packages install <packageId> --from <contextId> -c <groupId>; with --json that report is under requirements.

promote says what the group runs, including when it already selected that version. If the selection stays unchanged, it explains why and gives the activation command. Add --group to select the release for the group and follow it here (Admin), preserving pin and update policies. If activation fails, promotion is kept; retry activation. A Peers host too old for --group still promotes, but promote exits 1 and gives the activate ... --group command to run. JSON results include optional groupActivePackageVersionId, groupRunsPromotedVersion, and activationNote fields.

When the group's version isn't on this device, get warns that it may not have synced yet (requested.groupVersionMissing in JSON). Wait for sync, or select an available release with peers packages activate <packageId> <packageVersionId> --group (Admin; same -c <groupId>).

--device targets must trust you as Self. In personal context, another account's device with that trust is reached only over a direct connection (for example on the same network), and the call runs in that device's own personal context. An explicit -c <groupId> keeps the call in that shared group and can use the mesh. See Administering your other devices.

peers git: Git repositories​

Share, list, clone and inspect repositories shared through the Git package. A repository is a name, a repository id, or a peers:// URL. In a working copy with a peers:// remote, status, policy and adopt default to that repository and its group. An explicit -c must agree with a URL's context, including -c personal.

peers git share [name] -c <groupId>      # in a working copy: share it, add a "peers" remote, push
peers git list -c <groupId> # repositories and their peers:// URLs
peers git clone <repo> [dir] -c <groupId>
peers git status [repo] # branches, their states, copies to this device
peers git policy [repo] # shared branches and maintainers
peers git policy [repo] --branch main --maintainers alice,bob [--threshold 2]
peers git policy [repo] --remove-branch release
peers git policy [repo] --default-branch main [--remove-branch master] # owner: change the default
peers git adopt [repo] # Admins: adopt a repository whose owner left
peers git doctor -c <groupId> # check Git, the helper, Peers and the package

share uses the folder's name unless you give one, and makes the current branch the shared default branch (--default-branch picks another). --no-push adds the remote without pushing; --remote <name> names it. In a package's folder it also records the URL as the package's source when the package has none. policy --default-branch makes an already shared branch the default, the one clones check out (Git). Maintainers are named by their branch prefix or user id. Every command takes --json; Git's progress then goes to stderr. doctor exits 1 when a check fails. With detached HEAD, check out a branch before sharing, or use --no-push to create an empty remote.

peers new-id: New ids​

peers new-id        # one new Peers id
peers new-id 5 # five, one per line (at most 1000)

Prints new Peers ids for a package, contract, or screen: 25 letters and digits, the same kind newid() from @peers-app/peers-sdk makes in code. It runs locally, so the app needn't be running.

peers contracts add: Contract declarations​

From your package folder, generate a declaration from a contract registered on the running host:

peers contracts add <contractId>@<version> -c <groupId>
peers contracts add <contractId>@<version> --check --json

The default context is personal. The command writes src/contracts/<name>.v<version>.ts. --dir <folder> selects the local package folder; --out-dir <folder> is relative to it; --name <Name> changes the export name. --device <deviceId> reads another device that trusts you as Self, while writing locally. --json prints { path, exportName, changed }. --check writes nothing and exits 1 if the declaration is missing or out of date.

If the contract isn't registered, use the offline route: peers-package contract add <module#export|bundle|json>. Both routes produce the same declaration; see contract declarations.

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" '{"name": "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 or set timers
  • Import, reload, and diagnose packages with peers packages (JSON output and exit codes)
  • Share, clone, and inspect Git repositories with peers git (--json throughout)
  • Inspect and interact with the UI via peers ui, and see it by opening the file peers ui screenshot prints
  • 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. Commands for contacts, groups, invites, folders, keys, packages, tools, ui, and app restart|quit call versioned system contracts over that socket. The db command still uses the desktop RPC bridge, which is being migrated to contracts. Remote operations use that desktop as a bridge to a versioned System Device Operations or System Logs contract over an existing verified device connection.

The Device Operations surface is deliberately portable: status, bounded read-only SQL, tool listing/lookup/execution, and logs. It does not expose arbitrary shell, filesystem, or unrestricted table access. UI control and restart/quit go through System Host Shell and package administration through System Packages instead. 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.