CLI

Easel CLI

Install the Easel CLI, sign in, and link a directory or monorepo to your projects.

The Easel CLI (easel) deploys from your working tree, inspects deployments, and reads request logs. It's published as @easel-sh/cli and is in alpha. You can still deploy from Git or the dashboard.

Install

Install the CLI globally, or run it with npx:

npm install -g @easel-sh/cli

npx @easel-sh/cli --help

Check the installed version with easel -V.

Log in

easel login opens your browser at app.easel.sh and asks which workspace to use. After you approve, the CLI saves a token for that workspace. easel whoami prints the signed-in user and active workspace.

easel login
easel whoami

You don't have to log in first: easel deploy and easel link open the browser to sign in when you run them in a terminal without a token.

Remove saved credentials with easel logout.

Use a token

The CLI picks a token in this order:

--token / -t
The EASEL_TOKEN environment variable
The token saved by easel login

For CI and other non-interactive shells, create a token in your workspace's Settings → Access Tokens and set EASEL_TOKEN:

export EASEL_TOKEN="your_access_token"
easel whoami --format json

Each token belongs to one workspace. Access Tokens also lists the tokens easel login created, so you can revoke them there.

Link a project

Linking tells later commands which project to use:

easel link

In a terminal, easel link offers the project that matches the folder name, lets you pick an existing project, or creates a new one with detected settings. Pass --yes to accept the defaults, or name the project:

easel link --project my-app

The link is saved to .easel/project.json in the current directory. Commit it if your team wants a shared default. Any command also takes --project to override the link.

Link a monorepo

When one repository holds several Easel projects, each with its own root directory, link them once from the repository root:

easel link --repo

In a terminal, choose projects by number (comma-separated) or all. In a non-interactive shell, name each one:

easel link --repo --project front --project web

This writes .easel/repo.json at the Git repository root, mapping each project to its root directory:

{
  "workspaceId": "…",
  "workspaceSlug": "…",
  "projects": [
    { "id": "…", "slug": "front", "directory": "apps/front" },
    { "id": "…", "slug": "web", "directory": "apps/web" }
  ]
}

Then run commands from any subdirectory. The CLI uses the project whose directory most closely contains your current directory:

cd apps/front && easel deploy
cd apps/web && easel logs

At the repository root, or when several projects match, pass --project or choose interactively. A .easel/project.json closer to your current directory takes precedence over repo.json. See Monorepos for root directories and shared packages.

Global options

These options work with every platform command:

Option	Description
`-t, --token <token>`	API token (overrides `EASEL_TOKEN` and saved credentials)
`-W, --workspace <slug_or_id>`	Workspace slug or ID
`-F, --format <human\|json>`	Output format (defaults to `human` in a terminal, `json` otherwise)
`--no-color`	Disable ANSI colors

Next steps

Troubleshooting

Trace a failing request, find the page for your symptom, and read Easel error codes.

Deploy

Upload a local project and create a preview or production deployment with easel deploy, locally or in CI.