@vitrinka/cli

The vitrinka CLI — capture screenshots, publish artifact sets, scaffold interactive artifacts, and arm the annotation-board watch monitor that feeds work to a listening AI session.

Since 3.0.0 the CLI is a compiled Go binary. This npm package is the launcher: bin/vitrinka.js resolves the binary for your platform and execs it. The binary arrives through per-platform packages declared as optionalDependencies (@vitrinka/cli-darwin-arm64 and friends), so npm fetches it from whatever registry your machine already uses — no postinstall download, no network surprise in sandboxed CI or behind a corporate proxy.

Install

npm i -g @vitrinka/cli
vitrinka setup        # one-command machine setup

vitrinka setup IS the onboarding: it prints a ✓/✗ table of every component, silently installs the harmless ones (the skills plugin into each runtime CLI it finds, a vitrinka shim on PATH, shell completion — all reversible), then asks [Y/n] only for the config-touchers: MCP registration, the write token (silent input, → the OS keyring) and the operator name.

vitrinka doctor          # server, token, operator, skills, shim, MCP
vitrinka doctor --fix    # repairs the repairable
vitrinka update          # update the CLI and every installed Claude Code / Codex plugin
vitrinka setup uninstall       # remove it all (--purge: token too)

Installing with --omit=optional / --no-optional skips the binary by design. The launcher then tells you which platform package is missing rather than failing as "command not found".

MCP

The MCP surface is served by the vitrinka server at /mcp and per workspace at /w/<workspace>/mcp, with OAuth 2.1 built in. vitrinka setup registers it for you. For Claude Code that is a remote HTTP entry — no local process per session; sign in once from inside Claude Code (/mcp → vitrinka → authenticate):

claude mcp add --scope project --transport http vitrinka https://app.vitrinka.ai/w/<workspace>/mcp

The same command renders the repo's committed vitrinka.config.json into every other harness's project-level file — Cursor (.cursor/mcp.json), OpenCode (opencode.json), VS Code (.vscode/mcp.json), Gemini CLI (.gemini/settings.json) — as a plain remote URL the harness signs into with its own OAuth flow; --harness <csv|all> picks them (default: Claude Code plus whatever is detected), entries merge into existing files, and vitrinka doctor reports drift. Every entry names the same root /mcp endpoint; the repo's workspace rides an X-Vitrinka-Workspace header, and the committed file spells the origin ${VITRINKA_URL:-https://app.vitrinka.ai} so a self-hosted developer exports one variable and the same file works. One OAuth sign-in per origin covers every workspace of your organisation — a call may name another as <workspace>/<project>. Through a user-level entry (root /mcp, no header) calls land in the grant's home workspace and writes reach only projects that already exist; the bound repo's project file is what allows creating them.

Codex registers the same door (codex mcp add vitrinka --url <origin>/mcp, then codex mcp login vitrinka); its registry is global, so the home workspace is the default there and <workspace>/<project> reaches the rest.

The stdio forwarder vitrinka mcp is retired (as is the older HTTP + Authorization: Bearer … shape that baked a credential into client config). vitrinka doctor flags either and vitrinka setup rewrites it.

vitrinka setup also links ~/.local/bin/vitrinka straight to the Go binary this package ships (on npm and bun; pnpm gets a copy that vitrinka update refreshes) and puts it first on PATH, so long-running commands (vitrinka work watch) run without the Node launcher idling as their parent. Updates still flow through your package manager.

vitrinka is an authenticated service at https://app.vitrinka.ai — sign up there (open beta), then vitrinka auth login signs the CLI in through the browser. Self-hosted deployments point the CLI at their own host with VITRINKA_URL (or --base).

Configuration (env)

| Var | Default | Purpose | |---|---|---| | VITRINKA_URL / VITRINKA_BASE_URL | https://app.vitrinka.ai | vitrinka server base URL. VITRINKA_URL wins, then VITRINKA_BASE_URL; the CLI's --base flag overrides both. | | VITRINKA_TOKEN | — | Bearer token. vitrinka auth login stores it in the OS keyring / ~/.config/vitrinka/; set the variable explicitly for CI. | | VITRINKA_OPERATOR | — | Operator persona name. When set, write calls carry X-Board-Actor: <name> so the board credits the operator — agent-authored content keeps its explicit claude attribution. |

Trustworthy project index

vitrinka setup or vitrinka project index configure creates the repository-owned vitrinka.config.json. The interactive picker chooses extension groups and any depth of directory tree, then shows the exact file manifest before approval. Choosing "later" writes an explicit disabled policy and uploads nothing.

The index contains repository-relative paths, derived routes, and repository command names only — never source bytes, absolute paths, remotes, command descriptions, or files from ~/.claude. .gitignore is an unconditional deny layer even for tracked files; detected .claudeignore is offered as another; untracked files require an explicit advanced opt-in; credential/key filenames and binary/generated assets are blocked by both client and server safety floors.

vitrinka project index configure              # edit, preview, approve, then refresh
vitrinka project index status                 # policy + local approval/upload receipt
vitrinka project index --dry-run              # exact paths, no network request
vitrinka project index --explain path/to/file # winning selection or deny rule

The config schema is served by the deployment at https://app.vitrinka.ai/static/vitrinka.config.schema.json — reference it from $schema in your vitrinka.config.json for editor completion.

Desktop app

~/.config/vitrinka/desktop-app is the ONE canonical "is Vitrinka.app installed here" answer (content = the app path). apps/desktop's make install stamps it; doctor and setup-project re-sync it to reality. vitrinka board open uses it to open boards in the app (pass --browser to force the browser), and vitrinka board edit [path] focuses the resident app on a file or project.

Development

This package carries no implementation; it is the npm front door only. The binaries are built and released from the vitrinka server repository; the public plugin, skills and issue tracker live in vitrinka-kit.

License

Elastic License 2.0 — see the LICENSE file shipped in this package.