@wall.cx/cli

Wall 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

npm install -g "@wall.cx/cli"

Requires Node.js >= 20.

Quick start

# 1. import an export ZIP and activate it
wall init ./[email protected]

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

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:

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:

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

{
  "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.