# CLI
> Every command the sparsh binary answers to, generated from its own usage text.
> Source: https://jvoltci.github.io/sparsh/docs/reference/cli/

{/* GENERATED by site/scripts/reference.mjs from frontend/src/peer/cli.ts.
    Do not edit: run `node scripts/reference.mjs`. */}

```bash
git clone https://github.com/jvoltci/sparsh && cd sparsh/frontend && npm install
npm run peer -- whoami
```

The npm package `sparsh-cli` is the reserved name, not a release yet: what is
published today is a placeholder that says so in its own description. Until it
ships, `npm run peer -- <command>` is `sparsh <command>`, and every form below
reads the same either way.

## Commands

| Command | What it does |
|---|---|
| `sparsh join <code> [--into DIR] [--once] [--json]` | receive from the device showing `<code>` |
| `sparsh send <path>... (--to <device> or --code <code>) [--json]` | send files to a device |
| `sparsh host [--into DIR] [--send <path>...] [--json]` | show a code; receive, or send once joined |
| `sparsh ping --code <code> [--count N] [--json]` | round trip to that device, min/median/p95 |
| `sparsh invite [--into DIR] [--json]` | show a link to pair with, no code |
| `sparsh pair <token> [--json]` | pair using a link someone showed you |
| `sparsh devices [--json]` | paired devices, and which are online now |
| `sparsh serve [--into DIR] [--json]` | stay resident: presence + warm sessions |
| `sparsh status [--json]` | is a daemon running, and what is warm |
| `sparsh receive [--into DIR] [--json]` | wait for a paired device, no code |
| `sparsh mcp-tools` | stdio MCP server: this machine's four tools, for your own agent |
| `sparsh mcp <device>` | stdio MCP endpoint for the server `<device>` exposes to you |
| `sparsh expose <device> -- <command> [args…]` | let `<device>` drive this MCP server on this machine |
| `sparsh unexpose <device>` | take that back; a live channel closes now |
| `sparsh whoami` | this device key, name and pairings |

## Environment

| Variable | Meaning |
|---|---|
| `SPARSH_SIGNALING_URL` | the signalling server the app is built with; Nostr relays if unset |
| `SPARSH_HOME` | identity + remembered devices (default ~/.sparsh) |
| `SPARSH_SITE_URL` | the site the join link points at |
| `SPARSH_LABEL` | the name the other device sees |

The older `TELEPORT_*` names are still read, for one release. Sparsh was called
Teleport until 2026-09-19, and dropping the old names would break every shell
profile and CI job that already sets them, silently.