Agent-Vercel — The Vercel CLI that fights back.
Stop losing hours to trailing newlines. Stop agents from running vercel deploy.
Table of Contents
Ever spent 45 minutes debugging why your app works locally but breaks on Vercel, only to discover a trailing newline in an environment variable?
# This looks fine...
echo "sk-abc123" | vercel env add SECRET_KEY production
# But echo adds a trailing \n, and now your API key is "sk-abc123\n"
# Your app breaks. Vercel shows no error. You question your career choices.Or maybe you've accidentally run vercel deploy and bypassed your entire CI/CD pipeline. Or your team keeps using preview when the project convention is dev.
avercel wraps the official Vercel CLI and fixes all of this — silently, automatically, no behavior change needed.
npm i -g avercelThat's it. Both avercel and vercel now go through avercel's guardrails. The real Vercel CLI is bundled inside — no separate install needed.
| Feature | What it does |
|---|---|
🧹 Patched env add |
Strips trailing whitespace/newlines from piped stdin — automatically |
🔍 env check |
Audits all your env vars for trailing whitespace (the silent killer) |
| 🚫 Disabled commands | Block dangerous commands like deploy with custom error messages |
| 🛑 Blocked environments | Prevent wrong env names (preview vs dev) with guidance |
| 🔀 Full passthrough | Everything else forwards to vercel exactly as-is — same stdin/stdout/stderr/exit code |
| 🤖 AgentSkill built-in | AI coding agents get avercel's guardrails automatically |
Use avercel exactly like you'd use vercel:
# These just work — forwarded to vercel as-is
avercel dev
avercel ls
avercel domains ls
# This is the magic — trailing newline stripped automatically
echo "sk-abc123" | avercel env add SECRET_KEY production
# → "avercel: stripped 1 trailing whitespace/newline character(s) from piped input"
# Audit existing env vars
avercel env check
# → ⚠️ Found 2 env var(s) with trailing whitespace/newlines:
# Variable Targets Problem
# ──────────────────────────────────────────────────
# DATABASE_URL production, preview trailing newline (\n)
# SECRET_KEY production trailing whitespace
# Blocked environment names show a helpful error
avercel env pull preview
# → ❌ This project uses 'dev' not 'preview'. Use: avercel env pull dev
# Blocked commands show your custom message
avercel deploy
# → ❌ Do not use `vercel deploy`. Push to GitHub and let the integration handle it.Want avercel to completely replace vercel?
# Install avercel globally — it registers both `avercel` AND `vercel` commands
npm i -g avercel
# That's it! All `vercel` commands now go through avercel's guardrails.
# If you had vercel installed separately, clean it up:
avercel takeover --forceAfter takeover:
vercel ls # → goes through avercel → forwarded to real vercel internally
vercel deploy # → blocked by your config → "❌ Use git push instead"
echo "val" | vercel env add # → trailing newline stripped automaticallyCreate .avercel/avercel.yaml in your project root (or ~/.avercel/avercel.yaml for global config). Project config overrides global.
# Block commands with custom messages
disabled:
deploy: "❌ Do not use `vercel deploy`. Push to GitHub — Vercel deploys on git push."
build: "❌ Do not use `vercel build`. Vercel builds automatically on deploy."
"env rm": "❌ Don't remove env vars directly."
# Block specific environment names
blocked_envs:
preview: "❌ This project uses 'dev' not 'preview'. Use: avercel env pull dev"
staging: "❌ No staging environment. Use 'production' or 'dev'."View active config:
avercel configBlock entire commands. When a user runs a disabled command, they see your custom error message and the command exits without forwarding to vercel.
Block specific environment names in env pull, env add, env ls, and env rm commands. This is not silent replacement — it's a loud error with guidance.
Audits all environment variables in your Vercel project for trailing whitespace and newlines.
# Uses .vercel/project.json for project ID (run `vercel link` first)
avercel env check
# Or specify explicitly
avercel env check --project prj_abc123 --token tkn_xyzToken sources (in order):
--tokenflagVERCEL_TOKENenvironment variable~/.vercel_tokenfile
┌─────────────────┐
│ avercel │
│ │
│ 1. Load config │
│ 2. Check if │
│ disabled │
│ 3. Check │
│ blocked_envs │
│ 4. Patch or │
│ passthrough │
└────────┬─────────┘
│
▼
┌─────────────────┐
│ vercel CLI │
│ (bundled dep) │
└─────────────────┘
- Passthrough: Resolves the bundled vercel binary from
node_modulesand spawns it — zero overhead, same experience - Patched
env add: Only intercepts stdin when piped, strips trailing whitespace, forwards to vercel env check: Calls Vercel API directly, never touches the CLI- Takeover:
avercel takeover --forceremoves standalone vercel and lets avercel own both bin names
| Alternative | Problem |
|---|---|
Be careful with echo |
You'll forget. Everyone forgets. |
Use printf |
Not all tools use printf. And you'll still forget. |
| Check env vars manually | There's no vercel env check command |
Alias deploy in your shell |
Doesn't help your teammates |
Use a .env file |
Doesn't solve the Vercel-side issue |
avercel ships with a built-in AgentSkill for AI coding agents.
Any agent that supports the AgentSkill format (Claude Code, Cursor, OpenClaw, etc.) can pick up avercel's guardrails automatically — blocked commands, env patching, and environment restrictions are enforced without the agent needing any special configuration.
# The skill file lives at:
skill/SKILL.md
Contributions welcome! See CONTRIBUTING.md.
MIT — see LICENSE.
If avercel saved you from a trailing newline nightmare, consider giving it a ⭐ on GitHub — it helps others discover the project.