# @wall.cx/cli

[Wall](https://wall.cx) data reader + self-hosted MCP server — single binary.

Reads Wall export ZIPs and serves them locally for personal viewing (`wall serve`), terminal browsing (`wall list / read / search`), and LLM access via the Model Context Protocol (`wall mcp`).

## Install

```bash
npm install -g @wall.cx/cli
```

Requires Node.js >= 20.

## Quick start

```bash
# 1. import an export ZIP and activate it
wall init ./wall-export-@you-2026-05-17.zip

# 2. terminal browsing
wall status                         # active export + cached exports
wall list                           # content type summary
wall list posts                     # one type as a table
wall read <id>                      # one item by short_id
wall search "<query>"               # substring search across all content
wall upstreams <id>                 # what this references
wall downstreams <id>               # what references this

# 3. web viewer (read-only SPA on 127.0.0.1)
wall serve --port 5174 --open

# 4. self-hosted MCP server (read-only tools over the active export)
wall mcp                            # HTTPS + cloudflared tunnel (claude.ai / ChatGPT)
wall mcp --local                    # HTTPS on 127.0.0.1 (VSCode / opencode / local agents)
wall mcp --stdio                    # Claude Desktop
```

## Output modes

Read-only commands (`list / read / search / upstreams / downstreams / status`) auto-detect:

- TTY (interactive shell) → pretty table
- non-TTY (pipe / redirect) → tab-separated (script-friendly)
- `--json` flag → JSON (recommended for LLM agents)

```bash
wall list posts --json | jq '.[].id'
wall search "wall" --json
```

## Cache layout

Exports are extracted into `~/.wall/open/<owner-handle>-<exportedAt-slug>/` and persist across runs. `~/.wall/state.json` tracks the active export. Manage caches:

```bash
wall import <path>           # extract only, don't activate
wall switch <cacheId>        # activate a cached export
wall status                  # list everything
wall clear [cacheId]         # delete (no arg = all)
```

`switch` supports exact match plus handle/exportedAt substring fallback. Ambiguous patterns:

```bash
wall switch 2026-05 --json   # list candidates without picking
wall switch 2026-05 --latest # pick the most recent match
```

## MCP server

`wall mcp` exposes 23 read-only tools over the active export — eight `get_<type>` and nine `list_<type>` plus `get_trail` (sanitized), `search`, `get_upstreams`, `get_downstreams`, `list_series_posts`, and `read_media`. `wall_ai_conversations` and raw Trail message bodies are intentionally withheld to protect the LLM context window. See [docs/spec/mcp.md](docs/spec/mcp.md) for the full surface and per-client setup.

### Transport modes

| Mode | Endpoint | Audience |
|---|---|---|
| `wall mcp` (default) | `https://*.trycloudflare.com` (Cloudflare-issued TLS, ephemeral subdomain) | claude.ai Custom Connector, ChatGPT — anything reaching from the public internet |
| `wall mcp --local` | `https://127.0.0.1:3000/` (self-signed cert at `~/.wall/tls/`) | VSCode native MCP, Cursor, Continue, Cline, opencode, local agents |
| `wall mcp --stdio` | stdin/stdout pipe | Claude Desktop |

### Claude Desktop config (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "wall": { "command": "wall", "args": ["mcp", "--stdio"] }
  }
}
```

`wall mcp --stdio` (interactive) also prints the config path and snippet for your platform.

## Security

- All servers bind to `127.0.0.1` only. Cloudflared (when used) tunnels over Cloudflare's edge cert, not the local self-signed one.
- All MCP tools are read-only — no write/delete surface.
- `read_media` resolves the requested path inside the cache directory and refuses any path that escapes via `..` or symlinks.
- `~/.wall/tls/key.pem` is created with `0600` permissions on Unix.
- Active export = local cache only; no DB access, no credentials, no network egress beyond the optional cloudflared tunnel.

## Versioning

Pre-1.0. `0.x` versions may break the schema or command surface; the package only loads exports whose `schemaVersion` matches its own major (currently `0`). Stable `1.0.0` will lock the command surface and bump on incompatible changes.

## License

MIT. Wall itself (`wall.cx`) is a separate hosted service.
