Authentication and Configuration

Configure your command-line interface (CLI) base URL and tokens so commands can reach your control plane securely.

About Authentication and Configuration

This section defines required connection values and how the CLI resolves them.

A base URL is the root endpoint for your Monolayer control plane application programming interface (API). An authentication token is a credential that authorizes a command.

Base URL Resolution

The CLI resolves the base URL in this order:

1. The --base-url flag.
2. The MONOLAYER_BASE_URL environment variable.

When neither value is available, the command exits with this message:

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

Token Requirements

Different commands use different token sources.

Token Resolution Order

When you run projects:list, the CLI resolves the token in this order:

1. The --auth-token flag.
2. The MONOLAYER_AUTH_TOKEN environment variable.

When the token is missing, the command exits with this message:

Missing auth token. Pass --auth-token explicitly or set MONOLAYER_AUTH_TOKEN.

When you run deployments:deploy, the CLI resolves the token in this order:

1. The --auth-token flag.
2. The MONOLAYER_DEPLOYMENT_TOKEN environment variable.

When the deployment token does not match the required format, the command exits with this message:

auth-token must start with "deploy_token_"

IMPORTANT: Deployment tokens must start with deploy_token_.

Using Authentication and Configuration

This section provides a repeatable setup procedure for local terminal sessions.

Concept and Goal

Use this procedure to configure environment variables and override values with flags when needed.

Prerequisites

• You have your control plane base URL.
• You have a project auth token.
• You have a deployment token that begins with deploy_token_.

Numbered Steps

1. Export the required environment variables.

export MONOLAYER_BASE_URL="https://control-plane-domain"
export MONOLAYER_AUTH_TOKEN="token_xxx"
export MONOLAYER_DEPLOYMENT_TOKEN="deploy_token_xxx"

2. Run the project command with environment-based authentication.

npx mnlyr projects:list --limit 5

3. Run the deployment command with environment-based authentication.

npx mnlyr deployments:deploy --project-id proj-1 --branch-name main

4. Override values with flags when you need command-specific credentials.

npx mnlyr projects:list \
  --base-url https://control-plane-domain \
  --auth-token token_xxx \
  --limit 5

Expected Result

Each command uses the configured base URL and token source, then returns normal command output.

Troubleshooting

This section lists common configuration errors and their command output.

• Missing base URL: Missing base URL. Pass --base-url explicitly or set MONOLAYER_BASE_URL.
• Missing project token: Missing auth token. Pass --auth-token explicitly or set MONOLAYER_AUTH_TOKEN.
• Invalid deployment token: auth-token must start with "deploy_token_"