Envoyer CLI

Trigger, gate, monitor, and cancel Laravel Envoyer deployments from the repository you are already working in.

Envoyer CLI keeps deployment close to git. Pick a branch, optionally wait for pre-deploy checks, start the Envoyer deployment, then follow it until it finishes.

Getting Started

Install the CLI:

npm install -g @wardy484/envoyer

Log in with an Envoyer API token:

envoyer auth login

Initialize your repository:

envoyer init

Start a deployment:

envoyer deploy

You can also run it without installing globally:

npx @wardy484/envoyer --help

Common Commands

List recent deployments:

envoyer list

Cancel the latest running deployment:

envoyer cancel

Run pre-deploy checks without starting Envoyer:

envoyer wait

Why Envoyer CLI?

Envoyer is excellent at running deployments. This CLI fills the local workflow gap around it:

• Deploy the current git branch without opening a browser
• Require GitHub Actions to pass before Envoyer starts
• Keep project config committed while credentials stay local
• Use named Envoyer profiles for different accounts or environments
• Give coding agents a small, repeatable deploy prompt

Features

• Interactive project setup with .envoyer.yml
• Named Envoyer credential profiles stored outside the repository
• Current-branch deployments by default
• Optional GitHub Actions pre-deploy gate before Envoyer starts
• Recent deployment listing and running deployment cancellation
• Agent deploy prompt installer for Codex, Claude, Cursor, and opencode

Requirements

• Node.js 16.14 or newer
• Git
• An Envoyer API token
• GitHub CLI, only if you configure GitHub Actions pre-deploy gates

How It Works

1. envoyer init creates repository config in .envoyer.yml.
2. envoyer auth login stores your Envoyer API token outside the repository.
3. envoyer deploy starts a deployment.
4. If pre_deploy checks are configured, the CLI waits for them before starting Envoyer.
5. The CLI streams deployment status until Envoyer reports success or failure.

Configuration

envoyer init writes .envoyer.yml to the repository root.

name: my-app
envoyer:
  project: production
  default_branch: main
pre_deploy:
  - type: github_workflow
    workflow: build-assets.yml
    timeout_seconds: 900
    poll_interval_seconds: 5

Local credential selection is written to .envoyer.local.yml, which the CLI adds to .gitignore.

envoyer:
  profile: default

Keep .envoyer.yml committed. Keep .envoyer.local.yml private.

Deployments

Start a deployment:

envoyer deploy

Deploy the current git branch explicitly:

envoyer deploy --current

Deploy the configured default branch explicitly:

envoyer deploy --main

Run pre-deploy checks without starting Envoyer:

envoyer deploy --preflight-only

Deploy a different configured Envoyer project:

envoyer deploy --project production

List recent deployments:

envoyer list --limit 10

Cancel the latest running deployment:

envoyer cancel

Credentials

Save a token:

envoyer auth login

Save a named profile:

envoyer auth login --profile production --default

List profiles:

envoyer auth profiles

Check token access:

envoyer auth whoami

Remove saved credentials:

envoyer auth logout

Credentials are stored at:

~/.config/envoyer/credentials.json

Pre-Deploy Gates

When a github_workflow pre-deploy step is configured, envoyer deploy waits for the latest run of that workflow on the selected branch commit.

The deployment only starts when the workflow completes successfully. If the workflow fails or times out, Envoyer is not triggered.

You can run the same gate without starting a deployment:

envoyer wait

This is useful in CI-style local workflows where a build, test, or asset workflow must pass before production deployment begins.

Agent Deploy Prompt

The package includes a small deploy prompt that can be installed into common coding agents.

Install for Codex in the current repository:

envoyer skill install

Install globally:

envoyer skill install --global

Install for every supported agent:

envoyer skill install --all

Supported agents are Codex, Claude, Cursor, and opencode.

Agent JSON Mode

Use top-level --agent when another tool needs machine-readable output:

envoyer --agent deploy --current

Long-running deploy commands write JSON progress events to stderr. The final successful result stays as a single JSON object on stdout.

Command Reference

envoyer init [--force]
envoyer deploy [-c|--current] [-m|--main] [--preflight-only] [--project <name>]
envoyer wait
envoyer list [--limit <n>]
envoyer cancel

envoyer auth login [--profile <name>] [--default] [--base-url <url>] [--skip-validation]
envoyer auth whoami [--profile <name>]
envoyer auth profiles
envoyer auth logout

envoyer skill install [--agent <agent>] [--target-agent <agent>] [--all] [--global] [--repo]

Troubleshooting

envoyer deploy cannot find a project

Run envoyer init from the repository root and confirm .envoyer.yml has the expected envoyer.project value.

GitHub workflow gates never pass

Confirm the GitHub CLI is installed, authenticated, and can read the repository:

gh auth status
gh run list

Also confirm the configured workflow name matches the workflow file or workflow display name.

Wrong Envoyer credentials are used

Check the selected local profile:

envoyer auth profiles
cat .envoyer.local.yml

Change the repository profile with envoyer auth login --profile <name> --default, or edit .envoyer.local.yml.

Development

Install dependencies:

npm install

Run tests:

npm test

Contributing

Issues and pull requests are welcome. Keep changes small, focused, and covered by tests where behavior changes.

License

MIT. See LICENSE.

Disclaimer

Envoyer CLI is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Laravel, Laravel Envoyer, or Taylor Otwell.