Python package wrapper for Vercel CLI

vercel-cli packages the npm vercel CLI for Python environments. It vendors the npm package under vercel_cli/vendor/ and uses the bundled Node.js runtime provided by nodejs-wheel-binaries, so you can run vercel without installing Node.js.

It provides both a command-line interface and a Python API that other libraries can use programmatically instead of resorting to subprocess calls.

Quick start

Install:

pip install vercel-cli

Use (same arguments and behavior as the official npm CLI):

vercel --version
vercel login
vercel deploy

Use programmatically in Python (for libraries that depend on this package):

from vercel_cli import run_vercel

# Deploy current directory
exit_code = run_vercel(["deploy"])

# Deploy specific directory with custom environment
exit_code = run_vercel(
    ["deploy", "--prod"],
    cwd="/path/to/project",
    env={"VERCEL_TOKEN": "my-token"}
)

# Check version
exit_code = run_vercel(["--version"])

What this provides

No system Node.js required: The CLI runs via the Node binary from nodejs-wheel-binaries (currently Node 22.x).
Vendored npm package: The vercel npm package (production deps only) is checked into vercel_cli/vendor/.
Console entrypoint: The vercel command maps to vercel_cli.run:main, which executes vercel_cli/vendor/dist/vc.js with the bundled Node runtime.
Python API: The run_vercel() function allows other Python libraries to use Vercel CLI programmatically without subprocess calls, with secure environment variable handling.

Requirements

Python 3.8+
macOS, Linux, or Windows supported by the Node wheels

How it works

At runtime, vercel_cli.run locates vercel_cli/vendor/dist/vc.js and launches it via the Node executable exposed by nodejs_wheel_binaries. CLI arguments are passed through unchanged, while environment variables are handled securely.

Programmatic usage

When using this package as a dependency in other Python libraries, you can call Vercel CLI commands directly without using subprocess:

from vercel_cli import run_vercel
import tempfile
import os

def deploy_my_app(source_dir: str, token: str) -> bool:
    """Deploy an application to Vercel programmatically."""
    with tempfile.TemporaryDirectory() as temp_dir:
        # Copy your app to temp directory and modify as needed
        # ...

        # Deploy with custom environment
        env = {
            "VERCEL_TOKEN": token,
            "NODE_ENV": "production"
        }

        exit_code = run_vercel(
            ["deploy", "--prod", "--yes"],
            cwd=temp_dir,
            env=env
        )

        return exit_code == 0

# Usage
success = deploy_my_app("./my-app", "my-vercel-token")

The run_vercel() function accepts:

args: List of CLI arguments (same as command line)
cwd: Working directory for the command
env: Environment variables to set (passed directly to the Node.js runtime)

Security considerations

When using the env parameter, only explicitly provided environment variables are passed to the Vercel CLI. This prevents accidental leakage of sensitive environment variables from your Python process while still allowing you to set necessary variables like VERCEL_TOKEN.

Example with secure token handling:

from vercel_cli import run_vercel

# Secure: only VERCEL_TOKEN is passed to the CLI
exit_code = run_vercel(
    ["deploy", "--prod"],
    env={"VERCEL_TOKEN": "your-secure-token"}
)

This approach avoids common security pitfalls of subprocess environment variable handling.

Updating the vendored Vercel CLI (maintainers)

There are two ways to update the vendored npm package under vercel_cli/vendor/:

Manual update to a specific version

# Using the console script defined in pyproject.toml
uv run update-vendor 46.0.2
# or equivalently
uv run python scripts/update_vendor.py 46.0.2

This will:

fetch vercel@46.0.2 from npm,
verify integrity/shasum,
install production dependencies with npm install --omit=dev, and
copy the result into vercel_cli/vendor/.

Automatic check-and-release (GitHub Actions)

The workflow .github/workflows/release.yml checks npm latest and, if newer than the vendored version, will:

vendor the new version using scripts/check_and_update.py,
commit the changes and create a tag v<version>,
build distributions, and
publish to PyPI (requires PYPI_API_TOKEN).

Versioning

The Python package version is derived dynamically from the vendored package.json via Hatch’s version source:

[tool.hatch.version]
path = "vercel_cli/vendor/package.json"
pattern = '"version"\s*:\s*"(?P<version>[^\\"]+)"'

Development

Build backend: hatchling
Dependency management: uv (see uv.lock)
Tests: pytest with coverage in tests/
Lint/format: ruff; type-check: basedpyright

Common commands (using uv):

# Run tests with coverage
uv run pytest --cov=vercel_cli --cov-report=term-missing

# Lint and format
uv run ruff check .
uv run ruff format .

# Type-check
uv run basedpyright

# Build wheel and sdist
uv run --with build python -m build

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vercel_cli-58.5.1.tar.gz (3.8 MB view details)

Uploaded Aug 4, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

vercel_cli-58.5.1-py3-none-any.whl (4.3 MB view details)

Uploaded Aug 4, 2026 Python 3

File details

Details for the file vercel_cli-58.5.1.tar.gz.

File metadata

Download URL: vercel_cli-58.5.1.tar.gz
Upload date: Aug 4, 2026
Size: 3.8 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vercel_cli-58.5.1.tar.gz
Algorithm	Hash digest
SHA256	`b97f106779231889eaba9e915458a2439024e9061e05fa82ca727149b58454d0`
MD5	`171fe59cd8998fda8043abd5c4347145`
BLAKE2b-256	`cbb8891c0463afa02afad822bcffc17b1e1b0c7e9fe2a05daf6cd7b57cd8923b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for vercel_cli-58.5.1.tar.gz:

Publisher: release.yml on nuage-studio/vercel-cli-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: vercel_cli-58.5.1.tar.gz
- Subject digest: b97f106779231889eaba9e915458a2439024e9061e05fa82ca727149b58454d0
- Sigstore transparency entry: 2338305681
- Sigstore integration time: Aug 4, 2026
Source repository:
- Permalink: nuage-studio/vercel-cli-python@8f3fecf409acf874fb93fb501f2dfc374cb2027d
- Branch / Tag: refs/heads/main
- Owner: https://github.com/nuage-studio
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@8f3fecf409acf874fb93fb501f2dfc374cb2027d
- Trigger Event: schedule