Environment Variables

CloudCLI UI is configured using environment variables. For local development and self-hosted setups, you can define these in a .env file at the project root. Settings are read once at startup — change a value and restart the server (or your PM2/systemd unit) for it to take effect.

Getting Started

cp .env.example .env

Then edit .env with your preferred settings.

Precedence

Settings resolve in this order (first match wins):

1. CLI flags passed when starting the server — highest priority, one-shot overrides.
2. Process environment — variables set in your shell or by your supervisor (PM2, systemd, Docker).
3. .env file — committed defaults for a project. Never commit real secrets here.
4. Built-in defaults — what you get when nothing else is set.

This means cloudcli --port 8080 overrides any PORT value in .env, which is the pattern you want for one-off testing without editing files.

Available Variables

Custom Port

To run on a different port:

# Via .env
PORT=8080

# Via CLI flag (overrides .env)
cloudcli --port 8080

Running more than one CloudCLI UI on the same machine? Give each a distinct port (3001, 3002, …) and they will coexist without conflict. This is useful when you want one instance pinned to your daily workflow and a second instance tracking the main branch for feature preview.

Restricting Project Discovery

By default CloudCLI UI discovers all sessions under your home directory. To restrict it to a specific workspace:

WORKSPACES_ROOT=/home/user/projects

Enabling HTTPS

ENABLE_HTTPS=true

Turns on HTTPS serving. You will also need to supply certificate paths (see the self-hosting guide). For remote deployments, the simplest path is a reverse proxy (Caddy, Nginx, or Traefik) that handles TLS and forwards plain HTTP to the CloudCLI UI on localhost:3001 — fewer moving parts than terminating HTTPS in Node.

Production tips

• Run under a process supervisor (PM2, systemd) so it restarts on crash and reboot.
• Put a reverse proxy in front (Caddy/Nginx) for HTTPS, compression, and request logging.
• Pin WORKSPACES_ROOT to the specific directory you want exposed; leave ~ only for single-user laptop installs.

Troubleshooting

Use these checks when a configuration value does not behave the way you expect.