greenlight CLI

Reference

greenlight is a small command-line program that ships inside the Greenlight plugin, alongside the MCP server your coding agent connects to. Your agent runs it for you — you never have to type these commands yourself. It exists because a few things cannot travel over MCP: putting real configuration values into an app running on a machine, cloning a repository with a working token, and writing a file into that repository. It is also the fallback when your agent’s MCP connection is unavailable, since it holds its own Greenlight credential.

This page is here for two readers: someone who just watched the CLI do something on their screen and wants to know what it was, and an IT administrator deciding whether to allow it. The conceptual picture is in The agent protocol and Local development.

Signing in, as you experience it

The CLI needs to know who is asking, once per machine. Your agent runs greenlight login and Greenlight gives it two ways to finish, both ending in the same credential.

Usually your agent handles the whole thing. greenlight login prints a short code and returns immediately. If your agent has a working Greenlight connection it approves that code itself, runs the command again, and picks up the credential. You see nothing.

Sometimes you are asked to approve a code. When your agent cannot approve it — some setups have no working Greenlight connection — it will show you a link to the approval page on your Greenlight site and a six-character code to type there. That page asks the one question that catches a scam: only enter a code that you or your agent just created. Nobody at your organization will ever send you a code to type there. Anyone signed in to Greenlight can approve a code this way, including before you have built anything.

Once you approve, tell your agent, or simply wait — it re-runs the command and collects the credential. Re-running is always safe and never issues a second code, so if you see the same code twice, nothing has gone wrong.

A third path, if you are at the machine yourself. greenlight login --loopback opens your browser, signs you in there, and skips the code entirely. Completing that step also signs the same browser in to your Greenlight dashboard, so the Open dashboard button on the success page does not ask again.

Note

Whichever path is used, the CLI acts as you. Everything it does is attributed to your account and limited to your own access. It never receives a password or an upstream system’s credential — only proof of who is asking. If IT deactivates your account, it stops working immediately, like every other session.

Installation

Three ways to get it, in the order most people encounter them.

Bundled with the plugin (the default). Nothing to install. The plugin that connects your agent to Greenlight carries the CLI with it, already pointed at your organization’s Greenlight.

From your Greenlight site, for agents with no plugin support, and for technical users:

curl https://greenlight.<your-org>/cli/install.sh | sh

This serves your own installation’s copy, with your Greenlight address already built in. Trusting it is the same act as trusting your Greenlight site’s certificate — it is your organization’s server, not a third party’s. It installs to ~/.greenlight/bin unless GREENLIGHT_CLI_DEST says otherwise. The program itself is available at /cli/greenlight.mjs if you would rather fetch it directly.

From the public plugin repository, as a raw file fetch.

It is a single self-contained file that runs on Node.js, with no dependencies to install. Copies obtained the second and third ways stay current by re-running the one-liner.

Tip

For IT: rolling this out through agent policy — including which commands to pre-approve and which addresses to allow — is covered in The agent protocol.

Command reference

Run greenlight help for this list on your own machine, or greenlight <command> --help for one command’s flags.

Authentication

Command	What it does
greenlight login [--wait] [--timeout <s>] [--loopback]	Sign in. Returns quickly; safe to re-run.
greenlight whoami	Show the signed-in identity.
greenlight logout	Remove the stored credentials.

Builder commands

Each of these does the same thing as the MCP tool named beside it, so an agent gets the same result whichever surface it reaches for.

Command	What it does	MCP equivalent
apps list	List apps in your org.	listApps
apps show	Show one app: environment, grants, resources, pipeline.	getApp
apps register	Register a new app.	registerApp
apps discover	List apps in your org you can open.	discoverApps
integrations list	List systems grantable to an app or requestable personally.	listGrantableIntegrations
integrations connect	Ask IT to connect a system the org has not connected yet.	requestIntegrationConnection
request	Request personal access to a credential.	requestCredentialAccess
env list	Read an app’s environment contract. Values are withheld.	envList
env set	Set an app environment value.	envSet
env rm	Remove an app environment value.	envRemove
pipeline	Read a pipeline run; --wait waits until it finishes.	getPipelineRun
logs	Read app logs over a window.	getLogs
metrics	Latest CPU, memory, and restart snapshot.	getMetrics
metrics series	CPU or memory history over a window.	getMetricsSeries
knowledge list	List knowledge entries.	knowledgeList
knowledge get	Get one knowledge entry.	knowledgeGet
knowledge search	Full-text search over knowledge entries.	knowledgeSearch
knowledge asset list	List attached images — the org’s real logo, icon, wordmark, favicon.	knowledgeAssetList
knowledge propose	Propose a knowledge entry.	knowledgePropose
pr open	Open a governed pull request for an app branch.	createPullRequest
pr merge	Merge a pull request through the governed merge gate.	mergePullRequest
share	Add an app co-owner by email.	addCoOwner
unshare	Remove an app co-owner by email.	removeCoOwner
feedback	File a report about the Greenlight platform itself.	submitFeedback
skill · skill show	Print the Greenlight builder instructions.	getBuilderSkill

Running and diagnostics

Command	What it does
greenlight run [--app <id>] -- <cmd>	Run a development command with governed configuration injected. With --app, the run uses the app’s access; without it, your own. Extra values via --env K=V and --env-file <path>.
greenlight repo clone --app <id> [--dir <d>]	Clone the app repository with a minted token, which is never printed.
greenlight repo refresh --app <id> [--dir <d>]	Point an existing checkout at a fresh token.
greenlight preview --app <id> [--path <p>]	Produce a single-use preview URL for a deployed app.
greenlight curl --app <id> --path <p>	Make an authenticated request to a deployed app.
greenlight knowledge asset get <scope>/<topic>/<slug> --out <p>	Fetch a knowledge asset — your organization’s real logo, for instance — and write it into the repository, checked against its checksum.
greenlight doctor	Report configuration, sign-in state, and whether the server is reachable.
greenlight help [command]	Show the command list, or one command’s flags.

Values that could be sensitive — an environment value, a request body, a proposal — are read from standard input or a --*-file path rather than typed on the command line, where other programs on the machine could read them.

Output and exit codes

Everything the CLI prints on standard output is JSON, because an agent reads it. Progress and status go to the error stream instead, each line prefixed with [greenlight]. When something fails, the JSON is an error object with a code, a message, and a request_id you can quote to your administrator.

The exit code tells a caller which kind of problem occurred:

Exit	Meaning
0	Success.
1	Something failed that does not fit the categories below.
2	The command was invoked incorrectly — an unknown flag or a malformed value. Nothing was contacted or changed.
3	A dead end for this attempt. The credential or sign-in request cannot be resumed; sign in again.
4	The request did not complete, and it is not a credential problem. Read code to find out which.

auth.approval_pending is the one you are most likely to see in an agent transcript, and it is not an error. It means sign-in is waiting on someone to approve the code — very often you. Exit 4 was deliberately separated from exit 3 for exactly this: “run the command again and it will work” and “this attempt is dead” call for opposite responses, and an agent that treats the first as fatal would stop halfway through signing in.

Always read code rather than relying on the exit status alone: the number narrows the category, it does not identify the failure.

Configuration

The CLI reads three environment variables. None is required in normal use.

Variable	Effect
GREENLIGHT_API_URL	Point the CLI at a different Greenlight. Your organization’s address is already built into the copy you have, so this is for testing and automation.
GREENLIGHT_CLI_KEYCHAIN	Set to 0 on macOS to store the credential in a file instead of the Keychain — useful on machines with no unlocked keychain.
GREENLIGHT_CLI_TOKEN	Supply a credential directly, for automated environments.

Where the credential lives. In the macOS Keychain by default on a Mac, and otherwise in a file readable only by you under ~/.greenlight. One entry per Greenlight site, so two installations on one machine never collide. It refreshes itself, so your agent is not interrupted to sign in again mid-build.

greenlight logout removes that credential from the machine. greenlight doctor reports which Greenlight it is pointed at, its version, where the credential is stored, whether it is signed in, and whether the server answers — the first thing to run when something is not working.

Next

MCP toolsThe tool catalog these commands mirror — inputs, outputs, and examples.

Local developmentHow your agent builds and runs your app against real, governed data.

Errors & paginationThe error envelope and codes behind the exit codes above.