CLI reference#

The midnight binary is two command sets in one process: a developer surface shaped for deploying from a project directory, and an operator surface for administering an installation.

Run midnight --help for the operator surface in full.

Session and link#

Command	Purpose
`midnight login --api-base <url> --email <address>`	Create a durable human session. Password and any one-time code are read without echo
`midnight whoami`	Show the server-verified identity and session
`midnight link`	Bind the directory to a project, environment and service; writes `.midnight/project.json`
`midnight status`	Show the current link
`midnight unlink`	Remove `.midnight/project.json`
`midnight logout`	Revoke the session, then remove it locally

Deployment#

Command	Purpose
`midnight up`	Deploy with the scoped human session
`midnight up --detach`	Deploy without following
`midnight redeploy`	Queue an immutable image and configuration replay
`midnight rollback --previous`	Return to the previous deployment
`midnight restart`	Restart the workload
`midnight stop`	Stop the workload
`midnight cancel`	Cancel the latest queued or running linked deployment
`midnight remove --deployment dep_...`	Remove a deployment
`midnight open`	Open the service

Observability#

Command	Purpose
`midnight logs -f`	Stream the latest deploy's logs
`midnight observability logs --project-id ... --service-id ... --follow`	Follow a named service
`midnight observability metrics --project-id ... --service-id ...`	Service metrics

Environments#

Command	Purpose
`midnight environment list --project-id prj_...`	List, with resource versions
`midnight environment create --project-id ... --name ... --tier ... <slug>`	Create
`midnight environment update --expected-version <n> [--slug\|--name\|--tier] env_...`	Compare-and-swap metadata update

Human callers need environment.write on the exact project. create rejects --protected. update accepts only an explicit partial --slug, --name or --tier, plus the positive resource version shown by list or get.

Protected-state changes, delete, duplicate, configuration copy and runtime application are recovery-only or separately gated, even though the shared CLI retains recovery commands.

Variables#

Command	Purpose
`midnight variable list --service-id ... --environment-id ...`	Metadata and current versions
`midnight variable set ... --scope <plain\|secret\|sealed> --stdin <NAME>`	Create — human `set` is create-only
`midnight variable update ... --expected-version <n> --stdin <id>`	Replace by identifier
`midnight variable delete ... --expected-version <n> <id>`	Delete

Full behaviour in Variables and secrets.

Domains#

Command	Purpose
`midnight domain list`	List
`midnight domain add`	Add a generated domain
`midnight domain get dom_...`	Read
`midnight domain delete --expected-version <n> dom_...`	Delete

Source binding#

Command	Purpose
`midnight service github repositories`	Discover repositories in project-workspace grants
`midnight service github branches --repository-id <id>`	Live-verify branches
`midnight service github link --installation-id ... --repository-id ... --branch main`	Link a service to a repository and branch

Automation credentials#

Command	Purpose
`midnight token create --name <name>`	Create a project-scoped credential. The raw value is shown once

Supply it as MIDNIGHT_TOKEN for automated deploys.

Operator surface#

Command	Purpose
`midnight admin generate-bootstrap-token`	Bootstrap credential
`midnight audit verify`	Verify the audit ledger
`midnight config apply`	Apply configuration
`midnight version`	Version
`midnight completion <shell>`	Generate completion for bash, zsh, fish or powershell

Idempotency#

Creation and update commands accept --idempotency-key. Omitted, the CLI derives a stable key from the request intent — for human mutations, a versioned HMAC over the session and exact route and body, whose visible form contains no raw or guessable value digest.

Important

On an uncertain or lost response, retry with the same key and unchanged arguments. Starting a new mutation risks duplicating the resource.

Credential rules#

Human sessions cover identity, tenant-scoped discovery for link, project creation, ordinary unprotected environment creation, strict environment metadata update, service-variable metadata and compare-and-swap writes, one generated HTTP-domain lifecycle, project automation credential management, and project-scoped GitHub discovery and source linking.

Arbitrary explicit or environment-supplied non-human tokens are rejected before any variable request. Use a human login for tenant access, or the explicitly stored recovery credential for legacy compatibility.