# Python package wrapper for Vercel CLI
[](https://github.com/nuage-studio/vercel-cli-python/actions/workflows/test.yml)
[](https://codecov.io/gh/nuage-studio/vercel-cli-python)
[](https://www.python.org/)
**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**:
```bash
pip install vercel-cli
```
- **Use** (same arguments and behavior as the official npm CLI):
```bash
vercel --version
vercel login
vercel deploy
```
- **Use programmatically in Python** (for libraries that depend on this package):
```python
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:
```python
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:
```python
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/`:
1) Manual update to a specific version
```bash
# 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/`.
1) 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:
```toml
[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`):
```bash
# 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
```
Raw data
{
"_id": null,
"home_page": null,
"name": "vercel-cli",
"maintainer": "Nuage",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "cli, deployment, edge, functions, nodejs, npm, serverless, vercel, wrapper",
"author": "Nuage",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/93/f0/abab28e4d263c6bd7973c79c0e1b436bdb211db1eacacf07ddaab32f728c/vercel_cli-47.0.5.tar.gz",
"platform": null,
"description": "# Python package wrapper for Vercel CLI\n\n[](https://github.com/nuage-studio/vercel-cli-python/actions/workflows/test.yml)\n[](https://codecov.io/gh/nuage-studio/vercel-cli-python)\n[](https://www.python.org/)\n\n**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.\n\nIt provides both a command-line interface and a Python API that other libraries can use programmatically instead of resorting to subprocess calls.\n\n## Quick start\n\n- **Install**:\n\n```bash\npip install vercel-cli\n```\n\n- **Use** (same arguments and behavior as the official npm CLI):\n\n```bash\nvercel --version\nvercel login\nvercel deploy\n```\n\n- **Use programmatically in Python** (for libraries that depend on this package):\n\n```python\nfrom vercel_cli import run_vercel\n\n# Deploy current directory\nexit_code = run_vercel([\"deploy\"])\n\n# Deploy specific directory with custom environment\nexit_code = run_vercel(\n [\"deploy\", \"--prod\"],\n cwd=\"/path/to/project\",\n env={\"VERCEL_TOKEN\": \"my-token\"}\n)\n\n# Check version\nexit_code = run_vercel([\"--version\"])\n```\n\n## What this provides\n\n- **No system Node.js required**: The CLI runs via the Node binary from `nodejs-wheel-binaries` (currently Node 22.x).\n- **Vendored npm package**: The `vercel` npm package (production deps only) is checked into `vercel_cli/vendor/`.\n- **Console entrypoint**: The `vercel` command maps to `vercel_cli.run:main`, which executes `vercel_cli/vendor/dist/vc.js` with the bundled Node runtime.\n- **Python API**: The `run_vercel()` function allows other Python libraries to use Vercel CLI programmatically without subprocess calls, with secure environment variable handling.\n\n## Requirements\n\n- Python 3.8+\n- macOS, Linux, or Windows supported by the Node wheels\n\n## How it works\n\nAt 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.\n\n## Programmatic usage\n\nWhen using this package as a dependency in other Python libraries, you can call Vercel CLI commands directly without using subprocess:\n\n```python\nfrom vercel_cli import run_vercel\nimport tempfile\nimport os\n\ndef deploy_my_app(source_dir: str, token: str) -> bool:\n \"\"\"Deploy an application to Vercel programmatically.\"\"\"\n with tempfile.TemporaryDirectory() as temp_dir:\n # Copy your app to temp directory and modify as needed\n # ...\n\n # Deploy with custom environment\n env = {\n \"VERCEL_TOKEN\": token,\n \"NODE_ENV\": \"production\"\n }\n\n exit_code = run_vercel(\n [\"deploy\", \"--prod\", \"--yes\"],\n cwd=temp_dir,\n env=env\n )\n\n return exit_code == 0\n\n# Usage\nsuccess = deploy_my_app(\"./my-app\", \"my-vercel-token\")\n```\n\nThe `run_vercel()` function accepts:\n\n- `args`: List of CLI arguments (same as command line)\n- `cwd`: Working directory for the command\n- `env`: Environment variables to set (passed directly to the Node.js runtime)\n\n## Security considerations\n\nWhen 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`.\n\nExample with secure token handling:\n\n```python\nfrom vercel_cli import run_vercel\n\n# Secure: only VERCEL_TOKEN is passed to the CLI\nexit_code = run_vercel(\n [\"deploy\", \"--prod\"],\n env={\"VERCEL_TOKEN\": \"your-secure-token\"}\n)\n```\n\nThis approach avoids common security pitfalls of subprocess environment variable handling.\n\n## Updating the vendored Vercel CLI (maintainers)\n\nThere are two ways to update the vendored npm package under `vercel_cli/vendor/`:\n\n1) Manual update to a specific version\n\n```bash\n# Using the console script defined in pyproject.toml\nuv run update-vendor 46.0.2\n# or equivalently\nuv run python scripts/update_vendor.py 46.0.2\n```\n\nThis will:\n\n- fetch `vercel@46.0.2` from npm,\n- verify integrity/shasum,\n- install production dependencies with `npm install --omit=dev`, and\n- copy the result into `vercel_cli/vendor/`.\n\n1) Automatic check-and-release (GitHub Actions)\n\nThe workflow `.github/workflows/release.yml` checks npm `latest` and, if newer than the vendored version, will:\n\n- vendor the new version using `scripts/check_and_update.py`,\n- commit the changes and create a tag `v<version>`,\n- build distributions, and\n- publish to PyPI (requires `PYPI_API_TOKEN`).\n\n## Versioning\n\nThe Python package version is derived dynamically from the vendored `package.json` via Hatch\u2019s version source:\n\n```toml\n[tool.hatch.version]\npath = \"vercel_cli/vendor/package.json\"\npattern = '\"version\"\\s*:\\s*\"(?P<version>[^\\\\\"]+)\"'\n```\n\n## Development\n\n- Build backend: `hatchling`\n- Dependency management: `uv` (see `uv.lock`)\n- Tests: `pytest` with coverage in `tests/`\n- Lint/format: `ruff`; type-check: `basedpyright`\n\nCommon commands (using `uv`):\n\n```bash\n# Run tests with coverage\nuv run pytest --cov=vercel_cli --cov-report=term-missing\n\n# Lint and format\nuv run ruff check .\nuv run ruff format .\n\n# Type-check\nuv run basedpyright\n\n# Build wheel and sdist\nuv run --with build python -m build\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Vercel CLI packaged for Python (bundled Node.js, vendored npm)",
"version": "47.0.5",
"project_urls": {
"Documentation": "https://github.com/nuage-studio/vercel-cli-python#readme",
"Homepage": "https://github.com/nuage-studio/vercel-cli-python",
"Issues": "https://github.com/nuage-studio/vercel-cli-python/issues",
"Repository": "https://github.com/nuage-studio/vercel-cli-python"
},
"split_keywords": [
"cli",
" deployment",
" edge",
" functions",
" nodejs",
" npm",
" serverless",
" vercel",
" wrapper"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "034c7067616811b4db25be1a72fa1c42d429a1b8917847b32b824885a46258c1",
"md5": "0b1182632e333143316797d68f9e6f9d",
"sha256": "700fcb884c650c6b4408eee5fc3ae71d39ecd1f6e004640c6e3e7afb89a2a46e"
},
"downloads": -1,
"filename": "vercel_cli-47.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0b1182632e333143316797d68f9e6f9d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 2291169,
"upload_time": "2025-09-05T02:26:52",
"upload_time_iso_8601": "2025-09-05T02:26:52.173927Z",
"url": "https://files.pythonhosted.org/packages/03/4c/7067616811b4db25be1a72fa1c42d429a1b8917847b32b824885a46258c1/vercel_cli-47.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "93f0abab28e4d263c6bd7973c79c0e1b436bdb211db1eacacf07ddaab32f728c",
"md5": "6866e872749c0973e411e03f78bcdb64",
"sha256": "e85693c65d6062e0ea95ffe64feab729f2c012e09627b279a6053324c711a83f"
},
"downloads": -1,
"filename": "vercel_cli-47.0.5.tar.gz",
"has_sig": false,
"md5_digest": "6866e872749c0973e411e03f78bcdb64",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 2218378,
"upload_time": "2025-09-05T02:26:54",
"upload_time_iso_8601": "2025-09-05T02:26:54.116797Z",
"url": "https://files.pythonhosted.org/packages/93/f0/abab28e4d263c6bd7973c79c0e1b436bdb211db1eacacf07ddaab32f728c/vercel_cli-47.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-05 02:26:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nuage-studio",
"github_project": "vercel-cli-python#readme",
"github_not_found": true,
"lcname": "vercel-cli"
}
JSON
