CLI Reference

The standalone command-line launcher. Start a server, generate tokens, and open the web client.

Usage

terminal
# With npx (no install)
npx @walkie-talkie/cli@latest

# Or install globally
npm install -g @walkie-talkie/cli
walkie-talkie

Options

Flag	Description	Default
`-p, --port=<number>`	Port to listen on	`3456`
`-d, --dir=<path>`	Working directory for spawned terminals	Current directory
`-f, --force`	Kill any existing process on the port before starting	`false`
`-o, --open`	Open the web client in your default browser	`false`
`--no-history`	Don't capture recent commands to `state.yaml`	`false`
`-h, --help`	Show help message	-
`-v, --version`	Print version	-

Examples

terminal
# Start on a custom port and auto-open
walkie-talkie -p 8080 --open

# Force kill existing process on port 3456
walkie-talkie --force

# Set working directory to a specific project
walkie-talkie -d ~/projects/my-app --open

Output

When the server starts, the CLI displays:

An ASCII QR code you can scan from a mobile device
A URL with the token embedded (e.g. https://demo.walkie-talkie.dev?server=...&token=...)
The raw token value for manual entry
Server address and port

Session State

While the server runs, your open terminals — names, working directory and recent commands — are saved to .walkie-talkie/state.yaml in the working directory. Commit it to git: reconnecting to the repo later shows a "Welcome back" panel that lists your previous tabs and lets you reopen them.

.walkie-talkie/state.yaml
version: 1
terminals:
  - name: dev server
    shell: /bin/zsh
    cwd: ./web
    recentCommands:
      - pnpm dev
      - git status

Recent commands are captured heuristically and run through best-effort secret redaction (env-var assignments, --token/--password flags and URL credentials are masked). Review before committing, or pass --no-history to disable capture.

File Browsing

The web UI can browse and view files in the working directory, read-only and jailed to that directory (path traversal and symlink escapes are rejected). Served by GET /api/fs/list and GET /api/fs/read with Bearer auth.

Token Refresh

Tokens expire after 5 minutes and are single-use. To generate a new token without restarting the server:

terminal
# On macOS/Linux — send SIGUSR1 to the server process
kill -USR1 $(pgrep -f walkie-talkie)

Port Conflicts

If something is already listening on the port, the CLI will detect it and offer the --force flag. With --force, it runs:

# macOS/Linux
lsof -ti:<port> | xargs kill -9

# Windows
taskkill /F /PID <pid>