Deploy from the CLI

easel deploy uploads your working tree and creates a deployment that builds on Easel. Git is optional: the CLI hashes your files, uploads the ones Easel doesn't already have, and starts the build.

The CLI skips .env and .env.* files at any depth so secrets aren't uploaded. It also reads .easelignore and .vercelignore. To include a skipped file, add a negation such as !.env.example to .easelignore.

First deploy

In a folder that isn't linked yet, easel deploy signs you in if needed and then sets up the project:

npx @easel-sh/cli deploy

Set up "~/code/storefront"
? Found project "acme/storefront". Link to it? [Y/n]

If no project matches the folder name, link an existing one or create a new one:

? Link to existing project? [y/N] n
? Name? (storefront)
Detected Next.js (Build Command: next build, Output Directory: .next)
? Customize settings? [y/N]
Linked acme/storefront (saved to .easel/project.json)

The CLI asks Which workspace? first when you belong to more than one. The first deploy of a new project goes to Production. Pass --yes to accept every default without prompts.

Deploy

Create a Preview deployment:

easel deploy

Create a Production deployment. The CLI asks you to confirm unless you pass --yes:

easel deploy --prod

Wait until the deployment is Ready or fails:

easel deploy --wait

Whether a Production deployment starts serving your domains when it's Ready depends on Promote production builds automatically. The CLI doesn't promote or roll back; see Promote and roll back.

Monorepos

After easel link --repo, run easel deploy from any app directory. The CLI uploads the whole repository so the project's root directory and workspace packages outside it are available to the build. With --prebuilt, it uploads only the app directory's .vercel/output.

Prebuilt deploys

Build locally, then upload the Build Output API directory and skip the remote framework build:

vercel build
easel deploy --prebuilt --prod --yes --wait

Options

With --wait, the command exits with code 1 when the deployment ends in ERROR or CANCELLED. The global options also apply.

CI

Choose Git or the CLI

With the Git integration, Easel deploys every push and the repository is the source of truth. Use the CLI in CI when another system controls releases, or when you deploy generated source or prebuilt output. Don't run both for the same project, or each commit deploys twice; disconnect Git if the CLI takes over.

Authenticate

Create a token in your workspace's Settings → Access Tokens, store it as a CI secret, and expose it as EASEL_TOKEN. Don't print it or write it into build artifacts. See Use a token.

CI shells aren't interactive, so commit .easel/project.json or pass --project. Without either, easel deploy stops and asks for one.

Preview and production

# Preview
easel deploy --project my-app --wait --format json

# Production
easel deploy --project my-app --prod --yes --wait --format json

JSON output includes deployment.id, deployment.status, and deployment.primaryUrl. Run smoke tests against that unique URL before you promote, so you test exactly the build that will serve traffic.

Concurrency

Serialize Production deploys, for example with a concurrency group in your CI, so an older run can't finish and go live after a newer one. Cancel superseded builds from the dashboard; see Manage deployments.

Next steps

• Inspect deployments and logs
• Promote and roll back