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 tries two ways to finish, in that order — both ending in the same credential.

First, your own browser. When the CLI can reach a browser on the machine it is running on, greenlight login opens your default one. A browser already signed in to Greenlight flashes through to a success page and the sign-in is finished in seconds — nothing to type, nothing to tell your agent. If you are signed out, that tab lands on your organization’s sign-in screen; finishing there straight away works, but a first-time sign-in, a two-factor prompt, or a passkey usually takes longer than the CLI waits, and that is expected rather than a failure — it moves on to the code below. Completing the browser step also signs that same browser in to your Greenlight dashboard, so the Open dashboard button on the success page does not ask again.

Then, a short code. When no browser can be reached — your agent is running in the cloud, or on a machine with no browser at all — or when the browser tab was not finished in time, 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.

Open the link in a browser that is already signed in to Greenlight, usually your work browser profile. The page only shows the code box once it knows who you are, so a signed-out browser sends you through your organization’s sign-in first. A code lasts 10 minutes, and the CLI tells you how much of that is left.

Once you approve, tell your agent, or simply wait — it re-runs the command and collects the credential. While the code is still live, re-running never issues a second one, so if you see the same code twice, nothing has gone wrong. Once it has expired, the next run starts a fresh sign-in with a new code.

If you want the browser and nothing else, greenlight login --loopback skips the code entirely and waits up to five minutes for you to finish in the browser — for a person sitting at the machine who would rather not see a code at all. Your agent should not reach for it: plain login already tries your browser first, and --loopback has no code to fall back on when there is no browser to open.

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 — and you can end this one sign-in by itself, without anyone touching your account, under Settings → Plugin sign-ins.

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 — your browser first, else a code. 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
policies	List the checks the pipeline gate enforces for your organization.	getPolicies
inspect db	Run one read-only query against the app’s own database and show the rows.	inspectAppDb
inspect blob	List or look up files in the app’s own storage and show their metadata, never their contents.	inspectAppBlob
diagnostics	Runtime-health snapshot of a deployed app.	getAppDiagnostics
inspect integration-db	Run one query against a granted connected database (Azure SQL, Fabric); ordinary writes are rolled back. --param repeats, in @p1, @p2 order.	inspectIntegrationDb
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 editor by email.	addCoOwner
unshare	Remove an app editor by email.	removeCoOwner
feedback	File a report about the Greenlight platform itself. --origin observer and --fingerprint <hex> mark a report filed by the plugin’s observer hook.	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. A user passthrough integration acts as you either way, and the run prints a link to connect your account the first time. 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 observe-hook	Run by the Claude Code plugin’s end-of-turn hook, not by hand. Does nothing unless your organization has turned on Agent reports; then it may file one summarized report per session about Greenlight problems the agent worked around. It never prints and always exits 0.
greenlight token-usage-hook	Run by the Claude Code plugin when a session ends or starts, not by hand. Does nothing unless your organization has turned on Build token usage; then it sends the finished session’s token counts per model to your install, attributed to the app whose folder the session ended in. It never prints and always exits 0.
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 inspect api --integration <s> --path <p>	Make one request to a connected system you have access to and show the response. Greenlight applies the credential itself, so the credential never reaches your machine. Same as the inspectIntegrationApi MCP tool.
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. A request body for greenlight curl or greenlight inspect api, or a pull request body for greenlight pr open is optional, so those commands read standard input only when you pass --body-file -.

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.

When the CLI cannot reach Greenlight at all, because the name does not resolve or nothing answers, the message tells you to connect to your company network and retry. An installation on a private network answers only from there.

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.

Ending a sign-in remotely. greenlight logout clears the credential from the machine you are on. To end a sign-in you can’t reach — a machine you no longer have, or one you think is compromised — open Settings → Plugin sign-ins in the dashboard. It lists every sign-in acting as you, with when it happened and what the client called itself, and ending one stops it immediately; the CLI asks to sign in again the next time your agent uses it. Admins can end anyone’s.

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.