@everywheredev/cli

A Claude-Code-style TypeScript terminal client for the PocketDev host. It is a thin client to the Go host — it never owns the filesystem, git, PTY, or AI agent. It browses/edits the project, streams the terminal and activity feed, drives the HTTP proxy, and runs AI prompts, connecting to a FULL-REMOTE host (cloud + Ory Hydra OAuth2).

Full design: docs/architecture/cli.md.

Install

npm i -g @everywheredev/cli  # provides the `pocketdev` binary

Standalone single-file builds (Bun / Node SEA / pkg) for macOS/Linux are planned so it runs without a Node toolchain, including over SSH.

Local development install

To put the pocketdev command on your PATH from this working copy (no registry, no publish) — needs Node ≥ 20:

make cli-link            # from repo root: npm install + npm link (auto-builds via `prepare`)
# or, from cli/:  npm link

npm link symlinks this package globally, so pocketdev points at your source. After editing, rebuild and the linked command picks it up — keep a watcher running for a tight loop:

npm run build:watch      # rebuild dist/ on every save (run in a spare terminal)

Validate the published shape (the eventual npm i -g @everywheredev/cli experience) without touching the registry — npm pack builds the exact tarball files would ship (bin/, dist/, README.md):

npm pack                                  # → everywheredev-cli-0.1.0.tgz
npm i -g ./everywheredev-cli-0.1.0.tgz    # install it like a real user would
npm rm -g @everywheredev/cli              # ...then remove and re-link for dev

Remove the dev link with make cli-unlink (or npm unlink -g @everywheredev/cli).

Quick start

# Device-grant login against Ory Hydra, then run commands.
pocketdev --profile cloud login
pocketdev --profile cloud agents
pocketdev open src/index.ts
pocketdev agent "refactor the parser and run tests"

Architecture (foundation)

The pipeline mirrors Claude Code: entry binary → DI composition root → command/router → agent + tool loop (approval gate) → transport → renderer, with a session/transcript model and layered settings underneath.

Every external dependency is an injected interface (port); concretes are wired once at the DI composition root (src/di/container.ts, tsyringe). Nothing downstream branches on environment, so the command/tool/agent layer is uniform.

| Seam (port) | Concrete | | --- | --- | | AuthProvider | HydraOAuthAuthProvider (device grant + PKCE) | | HttpPort | HttpTransport → https://… | | StreamPort | WsStreamTransport → wss://…/ws | | TerminalPort | TerminalTransport over the stream | | SessionStore | FileSessionStore (JSONL + /api/sessions) |

Layout

cli/
├─ bin/pocketdev.js              # shebang shim → dist/index.js
└─ src/
   ├─ index.ts                   # bootstrap: reflect-metadata, buildContainer, route
   ├─ di/{container,tokens}.ts    # composition root + injection tokens
   ├─ core/{app,command-router,errors}.ts
   ├─ config/{ports,config-store,profile,defaults}.ts   # precedence flags>env>project>user>defaults
   ├─ transport/{ports,http-transport,ws-stream-transport,terminal-transport,composite-transport,reconnect}.ts
   ├─ auth/{ports,hydra-oauth-auth-provider,device-flow,pkce,keychain}.ts
   ├─ session/{ports,file-session-store}.ts
   └─ contract/index.ts          # thin re-export of @pocketdev/contract types (no drift)

Configuration & precedence

Highest wins:

1. CLI flags        --host, --profile, --print/-p, --json, --no-tty
2. Environment      POCKETDEV_HOST, POCKETDEV_PORT (4317),
                    POCKETDEV_PROJECT_ROOT, POCKETDEV_MAX_FILE_BYTES,
                    KRATOS_PUBLIC_URL, HYDRA_PUBLIC_URL, OIDC_ISSUER
3. Project config   ./.pocketdev/config.json
4. User config      ~/.pocketdev/config.json
5. Built-in defaults

Server-only variables (DATABASE_URL, REDIS_URL, CASBIN_WATCHER_CHANNEL, STRIPE_*, *_ADMIN_URL) are not consumed by the CLI — they belong to the host.

Authentication

• OAuth2 Device Authorization Grant + PKCE (RFC 8628 + 7636) against Ory Hydra; access JWT used as the Bearer header for REST and the WS handshake; tokens stored in the OS keychain with a chmod-0600 file fallback for headless/CI.

Scripts

npm run build       # tsc --noEmit (typecheck) → esbuild bundle+minify to a single dist/index.js
npm run build:watch # tsc --watch → rebuild dist/ on save (pairs with `npm link`)
npm run dev         # run from source via tsx
npm test            # vitest
npm run typecheck   # tsc --noEmit

License

Proprietary — internal PocketDev component.