deployments:deploy

Use the deployments:deploy command to trigger a deployment for a specific branch. The CLI automatically monitors the process and streams live status updates until the deployment completes.

Syntax

npx mnlyr deployments:deploy [options]

Options

Option	Description
`--base-url <url>`	The base URL of your control plane API. You can also set this using the `MONOLAYER_BASE_URL` environment variable.
`--auth-token <token>`	Your deployment token. You can also set this using the `MONOLAYER_DEPLOYMENT_TOKEN` environment variable.
`--project-id <id>`	The unique identifier for your project. This is required to monitor the deployment's progress.
`--branch-name <name>`	The branch you want to deploy. If omitted, the CLI defaults to your current Git branch.
`--poll-interval-ms <n>`	How often the CLI checks for updates, in milliseconds. The default is `2000`.
`-h`, `--help`	Displays help information for the command.

Examples

Deploy a specific branch

npx mnlyr deployments:deploy \
  --base-url https://control-plane-domain \
  --auth-token deploy_token_xxx \
  --project-id proj-1 \
  --branch-name main

Deploy using environment variables

MONOLAYER_BASE_URL="https://control-plane-domain" \
MONOLAYER_DEPLOYMENT_TOKEN="deploy_token_xxx" \
npx mnlyr deployments:deploy --project-id proj-1 --branch-name main

Deploy your current Git branch

MONOLAYER_BASE_URL="https://control-plane-domain" \
MONOLAYER_DEPLOYMENT_TOKEN="deploy_token_xxx" \
npx mnlyr deployments:deploy --project-id proj-1

How it works

When you initiate a deployment, the CLI follows these steps:

Identifies the branch: Uses the --branch-name flag, or auto-detects your current Git branch.
Triggers the deployment: Sends a request to start the process.
Monitors progress: If the deployment is successfully triggered, the CLI begins polling for updates. (If the deployment is skipped or queued, the CLI notifies you and exits.)
Streams logs: Outputs new log lines and status changes directly to your terminal. It intelligently skips empty lines and prevents duplicate log entries.
Completes: Stops polling when the deployment reaches a final state (Finished, Failed, or Queued). If the deployment fails, the CLI exits with an error.

The CLI outputs logs and status updates in a clear, human-readable format.

Guidelines

To ensure a successful deployment, keep the following rules in mind:

Your deployment token must begin with deploy_token_.
Your branch name must be a raw name. It cannot start with refs/heads/ or branch/.

Troubleshooting

If you encounter issues, review the common errors below or enable debugging to see detailed request information.

Missing base URL Missing base URL. Pass --base-url explicitly or set MONOLAYER_BASE_URL.

Invalid deployment token auth-token must start with "deploy_token_"

Invalid branch name Current branch must be a raw branch name (no "refs/heads/" or "branch/" prefix).

Branch detection failure Unable to determine current git branch. Run this command inside a git repository or pass --branch-name.

Localhost connection issues If you are testing on https://localhost:<port> and see a TypeError: fetch failed error:

If your local server uses HTTP, ensure your base URL is http://localhost:<port>.
If your local server uses HTTPS with a self-signed certificate, make sure the certificate is trusted on your machine.

Debugging

To view detailed request metadata, set the DEBUG environment variable to 1. Rest assured, your token values are automatically redacted from debug logs to keep your credentials safe.

DEBUG=1 npx mnlyr deployments:deploy \
  --base-url https://control-plane-domain \
  --auth-token deploy_token_xxx \
  --project-id proj-1 \
  --branch-name main

Use the deployments:deploy command to trigger a deployment for a specific branch. The CLI automatically monitors the process and streams live status updates until the deployment completes.

Syntax

npx mnlyr deployments:deploy [options]

Options

Option	Description
`--base-url <url>`	The base URL of your control plane API. You can also set this using the `MONOLAYER_BASE_URL` environment variable.
`--auth-token <token>`	Your deployment token. You can also set this using the `MONOLAYER_DEPLOYMENT_TOKEN` environment variable.
`--project-id <id>`	The unique identifier for your project. This is required to monitor the deployment's progress.
`--branch-name <name>`	The branch you want to deploy. If omitted, the CLI defaults to your current Git branch.
`--poll-interval-ms <n>`	How often the CLI checks for updates, in milliseconds. The default is `2000`.
`-h`, `--help`	Displays help information for the command.

Examples

Deploy a specific branch

npx mnlyr deployments:deploy \
  --base-url https://control-plane-domain \
  --auth-token deploy_token_xxx \
  --project-id proj-1 \
  --branch-name main

Deploy using environment variables

MONOLAYER_BASE_URL="https://control-plane-domain" \
MONOLAYER_DEPLOYMENT_TOKEN="deploy_token_xxx" \
npx mnlyr deployments:deploy --project-id proj-1 --branch-name main

Deploy your current Git branch

MONOLAYER_BASE_URL="https://control-plane-domain" \
MONOLAYER_DEPLOYMENT_TOKEN="deploy_token_xxx" \
npx mnlyr deployments:deploy --project-id proj-1

How it works

When you initiate a deployment, the CLI follows these steps:

Identifies the branch: Uses the --branch-name flag, or auto-detects your current Git branch.
Triggers the deployment: Sends a request to start the process.
Monitors progress: If the deployment is successfully triggered, the CLI begins polling for updates. (If the deployment is skipped or queued, the CLI notifies you and exits.)
Streams logs: Outputs new log lines and status changes directly to your terminal. It intelligently skips empty lines and prevents duplicate log entries.
Completes: Stops polling when the deployment reaches a final state (Finished, Failed, or Queued). If the deployment fails, the CLI exits with an error.

The CLI outputs logs and status updates in a clear, human-readable format.

Guidelines

To ensure a successful deployment, keep the following rules in mind:

Your deployment token must begin with deploy_token_.
Your branch name must be a raw name. It cannot start with refs/heads/ or branch/.

Troubleshooting

If you encounter issues, review the common errors below or enable debugging to see detailed request information.

Missing base URL Missing base URL. Pass --base-url explicitly or set MONOLAYER_BASE_URL.

Invalid deployment token auth-token must start with "deploy_token_"

Invalid branch name Current branch must be a raw branch name (no "refs/heads/" or "branch/" prefix).

Branch detection failure Unable to determine current git branch. Run this command inside a git repository or pass --branch-name.

Localhost connection issues If you are testing on https://localhost:<port> and see a TypeError: fetch failed error:

If your local server uses HTTP, ensure your base URL is http://localhost:<port>.
If your local server uses HTTPS with a self-signed certificate, make sure the certificate is trusted on your machine.

Debugging

To view detailed request metadata, set the DEBUG environment variable to 1. Rest assured, your token values are automatically redacted from debug logs to keep your credentials safe.

DEBUG=1 npx mnlyr deployments:deploy \
  --base-url https://control-plane-domain \
  --auth-token deploy_token_xxx \
  --project-id proj-1 \
  --branch-name main

deployments:deploy

Syntax

Options

Examples

How it works

Guidelines

Troubleshooting

Debugging

On this page

deployments:deploy

Syntax

Options

Examples

How it works

Guidelines

Troubleshooting

Debugging

On this page