Vercel CLI With Tokens

# Vercel CLI with Tokens

Deploy and manage projects on Vercel using the CLI with token-based authentication, without relying on `vercel login`.

## Step 1: Locate the Vercel Token

Before running any Vercel CLI commands, identify where the token is coming from. Work through these scenarios in order:

### A) `VERCEL_TOKEN` is already set in the environment

```bash printenv VERCEL_TOKEN ```

If this returns a value, you're ready. Skip to Step 2.

### B) Token is in a `.env` file under `VERCEL_TOKEN`

```bash grep '^VERCEL_TOKEN=' .env 2>/dev/null ```

If found, export it:

```bash export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-) ```

### C) Token is in a `.env` file under a different name

Look for any variable that looks like a Vercel token (Vercel tokens typically start with `vca_`):

```bash grep -i 'vercel' .env 2>/dev/null ```

Inspect the output to identify which variable holds the token, then export it as `VERCEL_TOKEN`:

```bash export VERCEL_TOKEN=$(grep '^<VARIABLE_NAME>=' .env | cut -d= -f2-) ```

### D) No token found — ask the user

If none of the above yield a token, ask the user to provide one. They can create a Vercel access token at vercel.com/account/tokens.

---

**Important:** Once `VERCEL_TOKEN` is exported as an environment variable, the Vercel CLI reads it natively — **do not pass it as a `--token` flag**. Putting secrets in command-line arguments exposes them in shell history and process listings.

```bash # Bad — token visible in shell history and process listings vercel deploy --token "vca_abc123"

# Good — CLI reads VERCEL_TOKEN from the environment export VERCEL_TOKEN="vca_abc123" vercel deploy ```

## Step 2: Locate the Project and Team

Similarly, check for the project ID and team scope. These let the CLI target the right project without needing `vercel link`.

```bash # Check environment printenv VERCEL_PROJECT_ID printenv VERCEL_ORG_ID

# Or check .env grep -i 'vercel' .env 2>/dev/null ```

**If you have a project URL** (e.g. `https://vercel.com/my-team/my-project`), extract the team slug:

```bash # e.g. "my-team" from "https://vercel.com/my-team/my-project" echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1 ```

**If you have both `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` in your environment**, export them — the CLI will use these automatically and skip any `.vercel/` directory:

```bash export VERCEL_ORG_ID="<org-id>" export VERCEL_PROJECT_ID="<project-id>" ```

Note: `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` must be set together — setting only one causes an error.

## CLI Setup

Ensure the Vercel CLI is installed and up to date:

```bash npm install -g vercel vercel --version ```

## Deploying a Project

Always deploy as **preview** unless the user explicitly requests production. Choose a method based on what you have available.

### Quick Deploy (have project ID — no linking needed)

When `VERCEL_TOKEN` and `VERCEL_PROJECT_ID` are set in the environment, deploy directly:

```bash vercel deploy -y --no-wait ```

With a team scope (either via `VERCEL_ORG_ID` or `--scope`):

```bash vercel deploy --scope <team-slug> -y --no-wait ```

Production (only when explicitly requested):

```bash vercel deploy --prod --scope <team-slug> -y --no-wait ```

Check status:

```bash vercel inspect <deployment-url> ```

### Full Deploy Flow (no project ID — need to link)

Use this when you have a token and team but no pre-existing project ID.

#### Check project state first

```bash # Does the project have a git remote? git remote get-url origin 2>/dev/null

# Is it already linked to a Vercel project? cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null ```

#### Link the project

**With git remote (preferred):**

```bash vercel link --repo --scope <team-slug> -y ```

Reads the git remote and connects to the matching Vercel project. Creates `.vercel/repo.json`. More reliable than plain `vercel link`, which matches by directory name.

**Without git remote:**

```bash vercel link --scope <team-slug> -y ```

Creates `.vercel/project.json`.

**Link to a specific project by name:**

```bash vercel link --project <project-name> --scope <team-slug> -y ```

If the project is already linked, check `orgId` in `.vercel/project.json` or `.vercel/repo.json` to verify it matches the intended team.

#### Deploy after linking

**A) Git Push Deploy — has git remote (preferred)**

Git pushes trigger automatic Vercel deployments.

1. **Ask the user before pushing.** Never push without explicit approval. 2. Commit and push: ```bash git add . git commit -m "deploy: <description of changes>" git push ``` 3. Vercel builds automatically. Non-production branches get preview deployments. 4. Retrieve the deployment URL: ```bash sleep 5 vercel ls --format json --scope <team-slug> ``` Find the latest entry in the `deployments` array.

**B) CLI Deploy — no git remote**

```bash vercel deploy --scope <team-slug> -y --no-wait ```

Check status: