{"_id":"@airshelf/vx","_rev":"5-7884a7f51fea69b3debd7b6c4e291f95","name":"@airshelf/vx","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@airshelf/vx","version":"0.1.0","keywords":["vercel","cli","deployment","bun","ai-agents","agent-experience","devtools","json"],"author":{"name":"Evgeny Oleynik"},"license":"MIT","_id":"@airshelf/vx@0.1.0","maintainers":[{"name":"airshelf","email":"evgeny@airshelf.ai"}],"homepage":"https://github.com/airshelf/vx","bugs":{"url":"https://github.com/airshelf/vx/issues"},"bin":{"vx":"dist/cli.js"},"dist":{"shasum":"4b14141f719f5018367dc67e4f34cb2db77fd14c","tarball":"https://registry.npmjs.org/@airshelf/vx/-/vx-0.1.0.tgz","fileCount":4,"integrity":"sha512-lR+5SPQvLUpwt3GRiQFQqFRhGn1Vwn/9kIi3mzN8dVjMf9HGDVrr1WS9CurV4Skt1l9toN9StwbD9jXwz8g3Gw==","signatures":[{"sig":"MEUCIQC1iM0zF38ezpTtTrUfUf5tDtt6oNinzL2Wb5G0dyiNewIgeFd9ibknhr34MZgk7Mt62lI5bDWXG8ASivM/2dJY9kM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":98464},"type":"module","gitHead":"ca7cb945967777ebcf8e5fec8e3a6f147432bb3b","scripts":{"test":"bun test","build":"bun build --compile ./src/cli.ts --outfile vx","build:npm":"bun build ./src/cli.ts --outdir dist --target bun","prepublishOnly":"bun run build:npm"},"_npmUser":{"name":"airshelf","email":"evgeny@airshelf.ai"},"repository":{"url":"git+https://github.com/airshelf/vx.git","type":"git"},"_npmVersion":"11.6.2","description":"Fast, agent-friendly Vercel CLI replacement. Bun-powered, JSON-first.","directories":{},"_nodeVersion":"25.2.1","dependencies":{"commander":"^13.1.0","picocolors":"^1.1.1"},"_hasShrinkwrap":false,"devDependencies":{"bun-types":"^1.3.10"},"_npmOperationalInternal":{"tmp":"tmp/vx_0.1.0_1772180288975_0.489297916197063","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@airshelf/vx","version":"0.1.1","keywords":["vercel","cli","deployment","bun","ai-agents","agent-experience","devtools","json"],"author":{"name":"Evgeny Oleynik"},"license":"MIT","_id":"@airshelf/vx@0.1.1","maintainers":[{"name":"airshelf","email":"evgeny@airshelf.ai"}],"homepage":"https://github.com/airshelf/vx","bugs":{"url":"https://github.com/airshelf/vx/issues"},"bin":{"vx":"dist/cli.js"},"dist":{"shasum":"ce0fd80cde59efb61c1583a21f52879d278dcbff","tarball":"https://registry.npmjs.org/@airshelf/vx/-/vx-0.1.1.tgz","fileCount":4,"integrity":"sha512-inLpOGaDQjYD/sxzeU9o3E1SAEDU9neAceN5IfKrwydiuO0GOC6HYgaS6Uhr++AmUxPuBgp4hm9mjhFigQfLFQ==","signatures":[{"sig":"MEYCIQD3PPpL2ANGCQWGvUKA1E2Ru0az65pslx9qMfF+/Nnm1QIhAK0LJhwbPyIz6TIGQ1jqSIuE0WRr7ey55J3Bfc4b3za3","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":98468},"type":"module","gitHead":"ca7cb945967777ebcf8e5fec8e3a6f147432bb3b","scripts":{"test":"bun test","build":"bun build --compile ./src/cli.ts --outfile vx","build:npm":"bun build ./src/cli.ts --outdir dist --target bun","prepublishOnly":"bun run build:npm"},"_npmUser":{"name":"airshelf","email":"evgeny@airshelf.ai"},"repository":{"url":"git+https://github.com/airshelf/vx.git","type":"git"},"_npmVersion":"11.6.2","description":"Fast, agent-friendly Vercel CLI replacement. Bun-powered, JSON-first.","directories":{},"_nodeVersion":"25.2.1","dependencies":{"commander":"^13.1.0","picocolors":"^1.1.1"},"_hasShrinkwrap":false,"devDependencies":{"bun-types":"^1.3.10"},"_npmOperationalInternal":{"tmp":"tmp/vx_0.1.1_1772180301797_0.800218113043546","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@airshelf/vx","version":"0.2.0","keywords":["vercel","cli","deployment","bun","ai-agents","agent-experience","devtools","json"],"author":{"name":"Evgeny Oleynik"},"license":"MIT","_id":"@airshelf/vx@0.2.0","maintainers":[{"name":"airshelf","email":"evgeny@airshelf.ai"}],"homepage":"https://github.com/airshelf/vx","bugs":{"url":"https://github.com/airshelf/vx/issues"},"bin":{"vx":"dist/cli.js"},"dist":{"shasum":"f1fb9c90230928ed02cb79736ee7f7cc1a547bf1","tarball":"https://registry.npmjs.org/@airshelf/vx/-/vx-0.2.0.tgz","fileCount":4,"integrity":"sha512-RF3/CmNo2OyaYWn1BUBJC21eADuM/LcRhz2FI/YlAIdqrRW8/ok5CxMpAk+2EC41KDa9BhNZAs+s63x/G3SPlQ==","signatures":[{"sig":"MEYCIQD5AXMTh320vMzfp15StSUn8zgadNYj3NiQHlTUbY8ZNgIhAKK8yAQKdp80HcA5L5GZooPjgak0We4RAgjzUTnSeVE9","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":107350},"type":"module","gitHead":"f5eb417a4cbdbb60245d1169b078a3d0de29681b","scripts":{"test":"bun test","build":"bun build --compile ./src/cli.ts --outfile vx","build:npm":"bun build ./src/cli.ts --outdir dist --target bun","prepublishOnly":"bun run build:npm"},"_npmUser":{"name":"airshelf","email":"evgeny@airshelf.ai"},"repository":{"url":"git+https://github.com/airshelf/vx.git","type":"git"},"_npmVersion":"11.6.2","description":"Fast, agent-friendly Vercel CLI replacement. Bun-powered, JSON-first.","directories":{},"_nodeVersion":"25.2.1","dependencies":{"commander":"^13.1.0","picocolors":"^1.1.1"},"_hasShrinkwrap":false,"devDependencies":{"bun-types":"^1.3.10"},"_npmOperationalInternal":{"tmp":"tmp/vx_0.2.0_1772424436632_0.5676834177056655","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@airshelf/vx","version":"0.2.1","keywords":["vercel","cli","deployment","bun","ai-agents","agent-experience","devtools","json"],"author":{"name":"Evgeny Oleynik"},"license":"MIT","_id":"@airshelf/vx@0.2.1","maintainers":[{"name":"airshelf","email":"evgeny@airshelf.ai"}],"homepage":"https://github.com/airshelf/vx","bugs":{"url":"https://github.com/airshelf/vx/issues"},"bin":{"vx":"dist/cli.js"},"dist":{"shasum":"33a44f652fc02663444fc26c644e0ce9b80035d6","tarball":"https://registry.npmjs.org/@airshelf/vx/-/vx-0.2.1.tgz","fileCount":4,"integrity":"sha512-pcnq9nFWjdFWtUbK97mBW5mLh1vLC1Oci199VoD5qZrTLxqJenCGIeawnnOTLYJulgLfgZFMzWJ5DJDSJQTd9w==","signatures":[{"sig":"MEUCID4lMGD7wAVEqhkr5tnXHJnhA1lh/iMh7VeT2RJJ55yFAiEAyR8G0GFwhXzBW1epru3kQCMfrNYp9MhTUiED9v1ZDkg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":108878},"type":"module","gitHead":"4b26e2341423bc2dea27d940d48d02b637dddbb3","scripts":{"test":"bun test","build":"bun build --compile ./src/cli.ts --outfile vx","build:npm":"bun build ./src/cli.ts --outdir dist --target bun","prepublishOnly":"bun run build:npm"},"_npmUser":{"name":"airshelf","email":"evgeny@airshelf.ai"},"repository":{"url":"git+https://github.com/airshelf/vx.git","type":"git"},"_npmVersion":"11.6.2","description":"Fast, agent-friendly Vercel CLI replacement. Bun-powered, JSON-first.","directories":{},"_nodeVersion":"25.2.1","dependencies":{"commander":"^13.1.0","picocolors":"^1.1.1"},"_hasShrinkwrap":false,"devDependencies":{"bun-types":"^1.3.10"},"_npmOperationalInternal":{"tmp":"tmp/vx_0.2.1_1772430470925_0.9687488270465998","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@airshelf/vx","version":"0.3.0","description":"Fast, agent-friendly Vercel CLI replacement. Bun-powered, JSON-first.","type":"module","license":"MIT","author":{"name":"Evgeny Oleynik"},"repository":{"type":"git","url":"git+https://github.com/airshelf/vx.git"},"homepage":"https://github.com/airshelf/vx","keywords":["vercel","cli","deployment","bun","ai-agents","agent-experience","devtools","json"],"bin":{"vx":"dist/cli.js"},"scripts":{"build":"bun build --compile ./src/cli.ts --outfile vx","build:npm":"bun build ./src/cli.ts --outdir dist --target bun","prepublishOnly":"bun run build:npm","test":"bun test"},"dependencies":{"@modelcontextprotocol/sdk":"^1.27.1","commander":"^13.1.0","picocolors":"^1.1.1"},"devDependencies":{"bun-types":"^1.3.10"},"gitHead":"231063dc861606ffe66e5cea0fbbdf974c6d10ec","_id":"@airshelf/vx@0.3.0","bugs":{"url":"https://github.com/airshelf/vx/issues"},"_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-cqIx+QYM3eIqRQsfED07Y3kmqIbCzmvL5wTJJYgN5/2NKfxN4s2bzb5518Qo+x6Z7yfYCnqzmX1j74hz7QqaSA==","shasum":"dfb8703b8c6984f0477526ad9618fb3c13c7aab0","tarball":"https://registry.npmjs.org/@airshelf/vx/-/vx-0.3.0.tgz","fileCount":4,"unpackedSize":1162906,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDllgDDCWCkkXkj8ccKPYNuL5Dpip66IOlj/4FgcLupGgIhAOpnGxjLbkYQQG4xsWUm79jospFiQaVZM3vbE7hBTOm6"}]},"_npmUser":{"name":"airshelf","email":"evgeny@airshelf.ai"},"directories":{},"maintainers":[{"name":"airshelf","email":"evgeny@airshelf.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/vx_0.3.0_1778755240590_0.18365022679846166"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-27T08:18:08.911Z","modified":"2026-05-14T10:40:40.854Z","0.1.0":"2026-02-27T08:18:09.120Z","0.1.1":"2026-02-27T08:18:21.934Z","0.2.0":"2026-03-02T04:07:16.773Z","0.2.1":"2026-03-02T05:47:51.061Z","0.3.0":"2026-05-14T10:40:40.755Z"},"bugs":{"url":"https://github.com/airshelf/vx/issues"},"author":{"name":"Evgeny Oleynik"},"license":"MIT","homepage":"https://github.com/airshelf/vx","keywords":["vercel","cli","deployment","bun","ai-agents","agent-experience","devtools","json"],"repository":{"type":"git","url":"git+https://github.com/airshelf/vx.git"},"description":"Fast, agent-friendly Vercel CLI replacement. Bun-powered, JSON-first.","maintainers":[{"name":"airshelf","email":"evgeny@airshelf.ai"}],"readme":"# vx\n\nFast, agent-friendly Vercel CLI replacement. Wraps the Vercel REST API directly — no SDK, no framework overhead. Designed for both humans and AI agents. Includes an MCP resource server for zero-schema AI integration.\n\n## Why?\n\n| Pain point | `vercel` | `vx` |\n|---|---|---|\n| `vercel logs` hangs 5 min then times out | Silent hang | Configurable `--timeout`, clean exit |\n| `vercel link` silently rewires to wrong project | No confirmation | Reads `.vercel/project.json`, never modifies it |\n| `vercel ls` output is noisy and hard to parse | Wall of text | Clean table, `--json` for piping |\n| `vercel env pull` overwrites `.env.local` | Overwrites silently | Read-only — never touches local files |\n| No JSON output for scripting | Limited | `--json` on every command |\n| Slow startup | Node.js overhead | Bun — instant |\n\n## Install\n\n```bash\nbun install -g @airshelf/vx\n```\n\nOr run directly:\n\n```bash\nbunx @airshelf/vx ls\n```\n\n## Auth\n\nvx reads your existing Vercel credentials — zero config if you've used `vercel` before:\n\n1. `VERCEL_TOKEN` environment variable (highest priority)\n2. `~/.local/share/com.vercel.cli/auth.json` (Vercel CLI token)\n\nTeam context is read from `~/.local/share/com.vercel.cli/config.json`.\nProject context is read from `.vercel/project.json` — vx walks up from the current directory to find it (works in subdirectories and git worktrees).\n\n## Commands\n\n### `vx ls` — list deployments\n\n```bash\nvx ls                    # last 10 deployments\nvx ls --prod             # production only\nvx ls --latest --json    # single deployment object (not array)\nvx ls --limit 20         # more results\nvx ls --state ERROR      # filter by state\nvx ls --json             # raw JSON output\nvx ls --wait             # poll until latest deployment is READY or ERROR\nvx ls --wait --json      # same, with JSON output\n```\n\n### `vx logs build <url>` — build logs\n\n```bash\nvx logs build my-app-abc123.vercel.app           # stream build output (30s timeout)\nvx logs build my-app-abc123.vercel.app --no-follow  # fetch once\nvx logs build my-app-abc123.vercel.app --timeout 60000  # extend timeout\n```\n\n### `vx logs runtime <url>` — runtime logs\n\n```bash\nvx logs runtime -m 15 -n 50                      # last 15min, 50 entries\nvx logs runtime -p /api/shop -g \"error\"          # filter by path and text\nvx logs runtime --no-follow --timeout 5000       # accepted (runtime is always one-shot)\nvx logs runtime --json                           # raw JSON lines\n```\n\n### `vx env` — manage environment variables\n\n```bash\nvx env                        # list env vars for linked project\nvx env DATABASE_URL           # filter by key name (substring match)\nvx env --decrypt              # show values\nvx env --target production    # filter by environment\nvx env --json                 # raw JSON\nvx env set MY_KEY=myvalue     # set env var (all targets)\nvx env set MY_KEY=v --target production preview  # specific targets\nvx env rm MY_KEY              # remove env var\n```\n\n### `vx domains` — list domains\n\n```bash\nvx domains              # list all domains\nvx domains --limit 50   # more results\nvx domains --json       # raw JSON\n```\n\n### `vx projects` — list or find projects\n\n```bash\nvx projects                    # list all projects\nvx projects --json             # raw JSON\nvx projects my-app             # find project by name or ID\nvx projects my-app --json      # project details as JSON\n```\n\n### `vx redeploy` — redeploy a deployment\n\n```bash\nvx redeploy                              # redeploy latest deployment\nvx redeploy my-app-abc123.vercel.app     # redeploy specific URL\nvx redeploy --target preview             # target preview instead of production\nvx redeploy --json                       # raw JSON\n```\n\n### `vx mcp` — MCP resource server\n\nStarts an MCP resource server on stdio. Exposes Vercel data as **resources instead of tools** — zero schema bloat, read-only, URI-based.\n\n```\nvercel://deployments                     # latest deployments (array)\nvercel://deployments/{url}               # single deployment\nvercel://deployments/{url}/logs/build    # build logs (text)\nvercel://deployments/{url}/logs/runtime  # runtime logs (text)\nvercel://projects                        # all projects (array)\nvercel://projects/{name}                 # single project\nvercel://projects/{name}/env             # env vars (array)\nvercel://domains                         # all domains (array)\n```\n\n**Why resources instead of tools?** A typical MCP tool server ships dozens of tool definitions with full JSON schemas — ~20,000+ tokens of context consumed before the agent asks a single question. vx's resource catalog is ~300 tokens. That's a **65x reduction** in context cost. And since resources are read-only URIs, there are no parameters for agents to hallucinate.\n\nConfigure in Claude Code:\n\n```bash\nclaude mcp add -s user vx-resources -- vx mcp\n```\n\nOr in Claude Desktop (`claude_desktop_config.json`):\n\n```json\n{ \"mcpServers\": { \"vercel\": { \"command\": \"vx\", \"args\": [\"mcp\"] } } }\n```\n\n## Piping\n\nEvery command supports `--json` for machine-readable output:\n\n```bash\nvx ls --json | jq '.[0].url'\nvx env --json --decrypt | jq '.[] | select(.key == \"DATABASE_URL\") | .value'\nvx projects --json | jq '.[].name'\nvx domains --json | jq '.[].name'\n```\n\nAll `--json` output is bare arrays — no wrapper objects. Pipe directly to `jq '.[0]'`.\n\n## Use with AI agents\n\n**Option 1: MCP resources** (recommended for Claude Code / Claude Desktop)\n\n```bash\nclaude mcp add -s user vx-resources -- vx mcp\n```\n\nThe agent reads Vercel data as MCP resources (`vercel://deployments`, `vercel://projects/{name}/env`, etc.) — no tool schemas, no parameters, no jq. ~300 tokens of context vs ~20k for a typical MCP tool server.\n\n**Option 2: CLI** — add this to your project's `CLAUDE.md`:\n\n```markdown\n## Vercel\n\nUse `vx` for Vercel operations:\n- `vx ls --json` — list deployments\n- `vx ls --wait --json` — poll until latest deployment is READY or ERROR\n- `vx logs build <url> --no-follow --timeout 10000` — build logs\n- `vx logs runtime --no-follow --timeout 10000` — runtime logs (flags accepted gracefully)\n- `vx env --json --project <name>` — list env vars\n- `vx env KEY --json` — single env var lookup\n- `vx env set KEY=VALUE` — set env var\n- `vx ls --latest --json` — single deployment object (not array)\n- `vx domains --json` — domains\n- `vx projects --json` — projects\n- `vx redeploy` — redeploy latest deployment (or specify URL)\n- Deploy: `git push` (Vercel auto-deploys), then `vx ls --wait --json`\n- Auth: set `VERCEL_TOKEN` env var (get one at vercel.com/account/tokens)\n- All --json output is bare arrays — use `jq '.[0]'` not `jq '.deployments[0]'`\n- Never `2>&1 | jq` — stderr hints corrupt JSON parsing\n```\n\n## Agent Experience (AX) design principles\n\nvx is built for **Agent Experience** — the idea that AI agents are now users of developer tools. The same properties that make a tool work in shell scripts make it work with AI agents, plus a few extras.\n\n### The principles vx follows\n\n**1. Minimize output — every token costs context**\n\nAn agent's context window is its short-term memory. Every unnecessary character — separator lines, padding, decoration, verbose messages — pushes useful information out. Treat output as a budget: the less you spend on formatting, the more the agent can spend on reasoning. vx's table output has no separator lines. `--json` has no pretty-printing overhead. Error messages are one line.\n\n**2. Structured output by default**\n\nEvery command supports `--json`. Agents waste tokens parsing ASCII tables and ANSI codes — JSON preserves the structure the code already has internally.\n\n```bash\n# Agent-friendly: structured, parseable\nvx ls --json | jq '.deployments[] | {url, state}'\n\n# Human-friendly: colored table (default)\nvx ls\n```\n\n**3. stdout for data, stderr for noise**\n\nResults go to stdout. Warnings (rate limits, timeouts) go to stderr. An agent piping output never gets progress messages mixed into data.\n\n**4. No interactive prompts**\n\nvx never prompts for confirmation, opens a browser, or launches an editor. Auth is token-based (`VERCEL_TOKEN` env var or existing CLI config). Every operation is fully specified by its arguments.\n\n**5. Fail fast and loud**\n\nThe original `vercel logs` hangs silently for 5 minutes. vx has a `--timeout` flag (default 30s) and exits with a clear error message. Agents can detect failure and try something else.\n\n**6. Never mutate implicitly**\n\nvx never writes to local files. `vercel env pull` overwrites `.env.local` — vx reads env vars and prints them. `vercel link` rewires `.vercel/project.json` — vx only reads it. Mutations are limited to `vx redeploy` (re-triggers an existing deployment) and `vx env set`/`vx env rm` (manage env vars via API) — no arbitrary code, no repo IDs, no parameters to hallucinate.\n\n**7. Read existing state, don't create new state**\n\nvx reads auth from `~/.local/share/com.vercel.cli/auth.json` and project context from `.vercel/project.json`. It doesn't create its own config files. Zero setup if the Vercel CLI was used before.\n\n**8. Instant startup**\n\nBun compiles to a single binary. No Node.js framework boot, no plugin loading. In agent workflows where tools are called 40-60 times per session, startup latency compounds.\n\n**9. Guide on failure — empty results are the worst UX**\n\nWhen a tool returns nothing, the agent has zero signal. It doesn't know if the query was wrong, the scope was too narrow, or there's genuinely nothing. Print a diagnostic to stderr: what was searched, how much was searched, and what to try next. `claude-grep` prints `no matches for \"x\" (126 files, 7 days, current project) — try: -d 30, -a, -s`. One line turns a dead end into a next step.\n\n**10. Log usage for yourself — close the feedback loop**\n\nYou can't improve what you can't observe. Log one JSONL line per invocation — what was called, what flags, how many results, how long it took. Not for analytics dashboards — for YOU to see how agents actually use the tool. `claude-grep --usage` shows hit rate, empty patterns, retry chains, and BRE misuse. Every improvement in this list (BRE normalization, no-match hints) came from reading that log. The tool documents how to improve itself.\n\n### The AX checklist\n\nBuilding a CLI tool for AI agents? Check these:\n\n| Principle | Why it matters |\n|---|---|\n| Minimize output tokens | Context window is finite — decoration is waste |\n| `--json` on every command | Structured output eliminates parsing errors |\n| stdout = data, stderr = logs | Piping works, agents get clean data |\n| No interactive prompts | Agents can't type \"Y\" at a prompt |\n| Deterministic exit codes | 0 = success, non-zero = failure — binary signals |\n| `--timeout` on network ops | Silent hangs waste context and money |\n| Clear error messages | Agents retry based on error text — make it parseable |\n| Read-only by default | Mutations need explicit commands — constrain the surface |\n| Idempotent operations | Safe to retry — agents are iterative |\n| `--help` is the API contract | Agents discover capabilities from help text |\n| Fast startup | Sub-100ms — dozens of calls per session |\n| Guide on empty results | No output = dead end — print scope + suggestions to stderr |\n| Log usage locally | You can't improve what you can't observe — JSONL + `--usage` |\n| Remove the problem, don't document it | If agents consistently misuse an interface, fix the interface |\n\nThe meta-insight: the features developers are proudest of for humans (interactive wizards, spinners, guided flows) become the biggest obstacles for agents. **Good AX means boring: predictable, structured, silent, deterministic.**\n\n## Build from source\n\n```bash\ngit clone https://github.com/airshelf/vx.git\ncd vx\nbun install\nbun run build   # produces ./vx binary\nbun test        # 56 tests\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}