CLI (lfc)

lfc is the command-line interface for Lifecycle. It lets you view and manage preview environments (builds), redeploy services, stream logs, host static sites, and validate configuration — straight from your terminal. It is built for humans and agents: every command supports --json, human-readable messages go to stderr, and machine output goes to stdout.

The CLI ships with no deployment URLs baked in. You point it at your own Lifecycle deployment once with lfc init. All examples below use generic placeholder hosts such as https://lifecycle.example.com and myorg/myrepo — substitute your own values.

Overview

Requires Node ≥ 20.

--help everywhere. lfc <command> --help works on every command and subcommand and lists all flags.
--json everywhere. Add --json for machine-readable output, or set LFC_JSON=1 to enable it globally.
Humans and agents. Interactive prompts appear only on a TTY; without one, commands fail fast and name the missing flag/argument, so scripts and agents stay deterministic. Run lfc llms to print agent-oriented instructions.

How it works

lfc is a thin client over your Lifecycle deployment’s HTTP API. Nothing about your deployment is hard-coded — you configure it once and the CLI stores a profile locally.

Profiles. Each profile points at one deployment (API URL, optional UI URL, and auth settings). You can keep several (e.g. default, staging, local) and switch between them. Config lives at ~/.config/lifecycle-cli/config.json.
Authentication. Deployments that enforce SSO use Keycloak (Authorization Code + PKCE, or device code for headless machines). Tokens are cached per profile under ~/.config/lifecycle-cli/tokens/ and refresh automatically. Auth-less deployments (authEnabled: false) skip all of this.

Output & scripting. JSON goes to stdout; informational messages go to stderr. Commands return meaningful exit codes:

Code	Meaning
`0`	success
`1`	failure (API error, failed build, invalid schema)
`2`	watch timeout (`--watch` did not converge in time)
`3`	not found (unknown uuid, no matching build, no config file)
`4`	authentication error (not logged in, expired session)

⚠️

On exit code 4, run lfc login (or lfc login --device on a headless machine) and retry. Verify who you are with lfc whoami.

Configuration

Point the CLI at your deployment. Interactively:

Or non-interactively (for scripts, dotfiles, onboarding docs):

init verifies the URL is reachable, writes the profile, and (when auth is on) starts the SSO login. Useful flags: --ui-url (enables lfc builds open), --no-login (skip the login step), --device (device-code login), --name <profile>, --force (overwrite an existing profile).

Config file structure

Configuration lives at ~/.config/lifecycle-cli/config.json and holds one entry per deployment under profiles, with the active one named by currentProfile:

Field	Description
`apiUrl`	Base URL of the Lifecycle API (required).
`uiUrl`	Base URL of the Lifecycle UI (optional; enables `lfc builds open`).
`authEnabled`	Whether the deployment enforces SSO.
`keycloak.issuer`	Keycloak realm issuer URL (when `authEnabled` is `true`).
`keycloak.clientId`	OAuth client id (defaults to `lifecycle-cli`).

Manage profiles without editing the file by hand:

Environment variables

Variable	Effect
`LIFECYCLE_API_URL`	Override the API base URL.
`LFC_PROFILE`	Select the active profile by name.
`LFC_JSON=1`	Force JSON output globally.
`LFC_CONFIG_DIR`	Override the config directory location.

One-off usage with no saved config (auth-less deployments only):

Commands

Authentication

Builds (preview environments)

builds find resolves a build from a PR or branch — useful when you have a PR URL but not the uuid. A PR URL is self-contained; a bare PR number or a branch needs --repo. With --json it returns { found, build, matches } (more than one matches entry means the selector was ambiguous). Exit 0 found, 3 no build yet (e.g. the PR was just opened), 1 if the scan was truncated before resolving.

Per-build environment-variable overrides:

Services (within a build)

Pods & runtime logs

Schema validation

Exit 0 valid, 1 invalid (per-field errors printed), 3 no config file found.

Static sites

Diagnostics & agent instructions

Every command supports --help and --json. For scripting and automation, combine --json with a JSON processor, e.g. lfc builds get <uuid> --json | jq '.deploys[] | {name: .deployable.name, url: .publicUrl}'.

MCP Server Mission Control comment