Skip to main content

Stacklok CLI

Stacklok Enterprise

The Stacklok CLI is a component of Stacklok Enterprise. For a full comparison of ToolHive Community and Stacklok Enterprise capabilities, see Stacklok Enterprise.

The Stacklok CLI is the enterprise edition of the ToolHive CLI (thv). Everything in the open source thv works the same way. The Stacklok CLI adds OIDC authentication to your Stacklok Enterprise platform and enforces the policies your administrators define in the Enterprise Manager.

This page covers what the enterprise edition adds. For the base CLI workflows, see the ToolHive CLI guides.

How you get it​

Stacklok provides the CLI as part of your Enterprise subscription as the standalone thv-enterprise binary. Install it on a workstation, a server, or in your continuous integration environment, and authenticate it with thv login.

This is the enterprise build of thv. Command examples on this page use thv.

How it connects to the platform​

The CLI needs your platform URL before it can authenticate. It reads StacklokPlatformUrl from managed preferences first, from the macOS managed preferences property list or the Windows registry, then falls back to the STACKLOK_PLATFORM_URL environment variable.

Managed preferences are the option to prefer for a fleet: setting that one value through your device management tooling configures every installation, so nobody has to be told an address.

From that URL, the CLI discovers the OIDC issuer, client ID, and scopes from the platform's well-known configuration endpoint. You do not configure those by hand.

Authentication​

The Stacklok CLI adds two commands for managing your platform session:

  • thv login opens a browser to complete the OAuth flow against your platform. On success, the session is stored in your secrets store. Login also configures registry access, so later thv registry commands reuse the session instead of opening a second browser flow. Re-run thv login at any time to refresh the session and pick up administrator-side configuration changes.
  • thv logout clears the cached session token and OAuth configuration.

thv login discovers its settings from the platform, so you normally run it with no flags. To override the discovered values, use --client-id, --scopes, or --callback-port.

On a machine with no browser, such as a build agent, use a virtual API key instead of an interactive sign-in.

Policy enforcement​

After you sign in, the CLI fetches signed configuration from the Enterprise Manager and enforces the directives that apply to clients. Each directive carries an enforcement level: enforced directives are mandatory, while default directives set a value you can still override locally. See Enforcement levels.

Two directives shape what the CLI can do:

  • Registry. When the registry directive is enforced, the configured registry URL is locked. Attempts to change it with thv config set-registry or thv config unset-registry are blocked.
  • Non-registry servers. When this directive is enforced to disallow them, the CLI blocks running MCP servers that are not in your organization's approved registry. Use thv search to find approved servers instead.

For the full set of directives an administrator can configure, see Enterprise Manager policies.

Degraded mode​

When the CLI cannot reach the Enterprise Manager, it keeps working from its cached configuration and prints a [ToolHive Policy Warning] to standard error so you know policy may be stale. If your administrator sets the degraded mode policy to block new installations, the CLI blocks creating new MCP servers until it reconnects.

Next steps​