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 extends the ToolHive CLI (thv) with OIDC authentication and policies distributed by the Enterprise Manager.

For 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.

For fleet deployment, set this value through device management.

The CLI discovers the OIDC issuer, client ID, and scopes from the platform's well-known configuration endpoint.

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 control which MCP servers the CLI can run:

  • 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​