CLI reference

Use this page when you already know the workflow and need exact commands, options, supported values, and defaults. For a task-oriented walkthrough, start with Sync MCP clients.

LightNow CLI

Manage MCP servers centrally in LightNow and keep every local client in sync with the right runtime profile.

GitHub repositorySetup guide

1brew tap lightnow-ai/tap

2brew install lightnow-cli

3lightnow login

4lightnow sync --client codex

Installation

The CLI source and release repository is lightnow-ai/lightnow-cli.

Install the CLI with Homebrew:

brew tap lightnow-ai/tap
brew install lightnow-cli

Or install the CLI with pipx:

pipx install lightnow-cli

Requirements for Python-based installs:

• Python 3.11 or higher
• pipx
• a LightNow account

You can also install with uv:

uv tool install lightnow-cli

You can also install the CLI directly from the public repository:

pipx install git+https://github.com/lightnow-ai/lightnow-cli.git

Check the installed version:

lightnow --version

Authentication model

The LightNow CLI signs in with OAuth Device Authorization. lightnow login requests a device code from Keycloak, opens the browser approval URL, and polls until the browser approval is complete. The CLI never receives a browser redirect, which keeps the flow usable from local terminals, remote shells, and headless environments.

Tokens are stored in ~/.lightnow/config.json. Commands refresh expired access tokens automatically while the refresh token is still valid.

How to read this reference

Each command includes:

Field	Meaning
Usage	The command shape. Uppercase values are placeholders.
Options	Supported flags, accepted values, defaults, and behavior.
Notes	Operational details that matter for automation or security.

Usage

lightnow [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS]

Global options

Key	Type / values	Details
--version	boolean	Print the installed LightNow CLI version and exit.
--install-completion	shell completion	Install shell completion for the current shell.
--show-completion	shell completion	Print shell completion output so it can be copied or customized.
--help	boolean	Show help for the current command.

Command overview

Command	Details
lightnow login	Authenticate with LightNow using OAuth Device Authorization.
lightnow status	Show whether the local CLI session is valid.
lightnow whoami	Show the signed-in LightNow identity.
lightnow logout	Clear stored authentication tokens.
lightnow context	Select the default Personal or organization context for CLI commands.
lightnow search	Search MCP servers in the registry.
lightnow favorites	List favorited MCP servers for a user, tenant, or effective context.
lightnow info	Show details for one MCP server and optional version.
lightnow sync	Sync a LightNow runtime profile into a local MCP client configuration.
lightnow run	Run one profile server through LightNow-managed local config.
lightnow validate	Validate MCP server metadata, docs, and specs locally.
lightnow publish	Publish MCP server artifacts to the registry.

Authentication commands

lightnow login

Authenticate with LightNow.

lightnow login

Key	Type / values	Details
--help	boolean	Show command help.

Notes:

• Opens the browser approval URL for the fixed lightnow-cli Keycloak client.
• Stores tokens locally after approval.
• Does not use OAuth redirect URIs.

lightnow status

Show current authentication status.

lightnow status

Key	Type / values	Details
--help	boolean	Show command help.

lightnow whoami

Show current user information.

lightnow whoami

Key	Type / values	Details
--help	boolean	Show command help.

lightnow logout

Clear stored authentication tokens.

lightnow logout

Key	Type / values	Details
--help	boolean	Show command help.

Context commands

lightnow context

Select the default LightNow context for commands that can act on either your personal account or an organization.

lightnow context

Key	Type / values	Details
--show	boolean	Show the currently stored context.
--personal	boolean	Switch back to the personal account context.
--tenant	string	Select an organization by exact tenant ID or subdomain.

Examples:

lightnow context
lightnow context --tenant acme
lightnow context --personal
lightnow context --show

Notes:

• lightnow context lists the organizations available to your signed-in account and stores the selected context locally.
• After a context is stored, context-aware commands use it automatically: search, favorites, info, sync, run, and publish.
• Passing --tenant to an individual command overrides the stored context for that command only.
• Organization selection is resolved through the LightNow Admin API and stored as a tenant ID. Registry requests then send this tenant ID as X-Tenant.

Registry discovery commands

lightnow search

Search MCP servers in the LightNow Registry.

lightnow search QUERY [OPTIONS]

Key	Type / values	Details
QUERY	string	Search term, for example redis or github. Required.
--sort	string	Sort order supported by the Registry API.
--tenant	string	Override the stored context for this command.
--limit	integer	Maximum number of servers to return. Default: 10.
--cursor	string	Pagination cursor.
--show-cursor	boolean	Print the raw next-page cursor for scripted pagination.

Example:

lightnow search github --limit 5

lightnow favorites

Show MCP servers favorited for the selected context.

lightnow favorites [OPTIONS]

Key	Type / values	Details
--scope	effective, user, tenant, system, true	Favorite scope. Default: user.
--sort	string	Sort order supported by the Registry API.
--tenant	string	Override the stored context for this command.
--limit	integer	Maximum number of servers to return. Default: 10.
--cursor	string	Pagination cursor.
--show-cursor	boolean	Print the raw next-page cursor for scripted pagination.

lightnow info

Get detailed information about a specific MCP server.

lightnow info SERVER_ID [OPTIONS]

Key	Type / values	Details
SERVER_ID	string	Server ID to inspect. Required.
--version	string	Specific server version to retrieve.
--tenant	string	Override the stored context for this command.

Integration commands

lightnow sync

Sync a LightNow runtime profile into a local MCP client configuration.

lightnow sync --client CLIENT [OPTIONS]

Key	Type / values	Details
--client	supported client target	Target MCP client. Required.
--profile	string	Runtime profile. Default: default.
--tenant	string	Override the stored context for this command.
--format	toml, json, yaml, shell	Export format. Defaults to the selected client format.
--secret-mode	plaintext, placeholder	plaintext writes secret values after confirmation; placeholder writes ${SECRET_NAME} references. Default: plaintext.
--config-path	path	Target client configuration file.
--api-url	URL	Registry API base URL.
--dry-run	boolean	Print a redacted preview without writing.
--yes	boolean	Skip plaintext write confirmation.
--runner	boolean	Write lightnow run wrappers instead of client-side server configs.
--local-proxy	boolean	Write one LightNow Local Proxy entry instead of direct per-server config.
--from-settings	boolean	Read the desired sync mode from LightNow Config policy.
--local-proxy-url	URL	Local Proxy MCP URL for HTTP mode and proxy config. Default: http://127.0.0.1:8080/mcp.
--local-proxy-transport	stdio, http	Client-facing Local Proxy transport. Default: stdio.
--local-proxy-config-path	path	Local Proxy config file written by the CLI. Defaults to ~/.lightnow/lightnow-proxy/<client>.yaml.
--registry-ca-file	path	Optional CA bundle used by the Local Proxy for LightNow Registry/Auth TLS.

Examples:

lightnow sync --client codex --profile default
lightnow context --tenant acme
lightnow sync --client claude-code --profile default
lightnow sync --client claude-desktop --local-proxy
lightnow sync --client vscode --local-proxy
lightnow sync --client codex --from-settings
lightnow sync --client codex --profile default --dry-run
lightnow sync --client codex --profile default --runner

Supported client targets:

Client target	Default format	Default path
codex	TOML	~/.codex/config.toml
claude-desktop	JSON	~/Library/Application Support/Claude/claude_desktop_config.json
claude-code	JSON	~/.claude.json
cursor	JSON	~/.cursor/mcp.json
windsurf	JSON	~/.codeium/windsurf/mcp_config.json
continue	YAML	~/.continue/config.yaml
antigravity	JSON	~/.gemini/config/mcp_config.json
gemini-cli	JSON	~/.gemini/settings.json
librechat	YAML	./librechat.yaml
vscode	JSON	~/Library/Application Support/Code/User/mcp.json on macOS
mcp-inspector	shell	./lightnow-mcp-inspector.sh

Notes:

• --dry-run redacts known secret-like values.
• --local-proxy is the recommended local setup for supported desktop clients.
• --from-settings applies the LightNow Config policy for the selected client. For managed clients, LightNow decides whether to use Local Proxy mode or direct sync. If unmanaged client MCP servers are blocked by policy, they are removed during sync; if they are allowed, they remain and config-status reports mixed.
• --runner keeps secret values in LightNow and writes wrapper commands.
• JSON clients get a sibling .lightnow-managed.json manifest so future syncs know which entries LightNow owns.

lightnow config-status

Inspect whether a local MCP client is configured through the LightNow Local Proxy.

lightnow config-status --client CLIENT [OPTIONS]

Key	Type / values	Details
--client	supported client target	Target MCP client. Required.
--config-path	path	Client config file to inspect.
--format	toml, json, yaml, shell	Config format. Defaults to the selected client format.
--local-proxy-config-path	path	Expected Local Proxy config path.
--json	boolean	Print machine-readable status JSON.

Examples:

lightnow config-status --client codex
lightnow config-status --client claude-desktop --json

managed means the selected client is configured to use the LightNow Local Proxy. mixed means LightNow is present, but additional user-managed MCP servers are still configured beside it. This may be allowed by your organization, but those entries bypass LightNow monitoring and policy. Client-internal MCP entries are reported separately and do not make the config mixed.

When the Local Proxy config exists, the status also includes non-secret runtime posture such as selected profile, client transport, telemetry flag, policy mode and whether unmanaged client MCP servers are allowed. In JSON output these fields are exposed as local_proxy_profile, local_proxy_client_transport, local_proxy_telemetry_enabled, local_proxy_policy_mode and local_proxy_allow_unmanaged_client_servers. If policy mode is enforce and unmanaged servers remain in the client config, warnings includes policy_blocks_unmanaged_servers.

lightnow run

Run one MCP server through LightNow and inject secrets into the child process.

lightnow run --server SERVER [OPTIONS]

Key	Type / values	Details
--server	string	MCP server alias from the selected runtime profile. Required.
--profile	string	LightNow runtime profile. Default: default.
--tenant	string	Override the stored context for this command.
--api-url	URL	Registry API base URL.
--transport	stdio	Requested runtime transport. Default: stdio.

Example:

lightnow run --profile default --server sonarqube

Notes:

• The selected server must be linked to a registry server version.
• Secrets are injected only into the child MCP server process.
• Non-stdio transports are rejected.

Publishing commands

lightnow validate

Validate MCP server artifacts locally.

lightnow validate [OPTIONS]

Key	Type / values	Details
--server	path	Path to server.json.
--docs	path	Path to docs.md.
--spec	path	Path to an OpenAPI specification file.

Example:

lightnow validate --server server.json --docs docs.md --spec openapi.json

lightnow publish

Publish MCP server artifacts to the registry.

lightnow publish --server server.json [OPTIONS]

Key	Type / values	Details
--server	path	Path to server.json. Required.
--docs	path	Path to docs.md.
--spec	path	Path to an OpenAPI specification file.
--tenant	string	Override the stored context for this command.
--validate-only	boolean	Validate files without publishing.

Example server.json:

{
  "name": "your-namespace.example/memory",
  "version": "1.0.0",
  "description": "A runnable stdio MCP server example for validating LightNow CLI publish and sync workflows.",
  "transport": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-memory"]
  }
}

Validate and publish:

lightnow validate --server server.json --docs docs.md
lightnow publish --server server.json --docs docs.md

Replace your-namespace.example/memory with a namespace you own before publishing. After the server is added to a runtime profile in LightNow, it can be synced into local clients with lightnow sync.

Exit behavior

Condition	Behavior
Not authenticated	Prints a login prompt and exits non-zero.
Expired access token	Asks you to run lightnow login again.
Validation failure	Prints validation errors and exits non-zero.
Sync or runner failure	Prints a redacted error and exits non-zero.

Related resources

• Sync MCP clients: workflow guide for Codex, Claude Code, VS Code, and other MCP clients.
• Integrations & runtime profiles: how profiles are managed in the LightNow app.
• Ownership and verification: how registry ownership signals work.