@kruzer/cli

@kruzer/cli

krz is the command-line interface for the Kruzer platform. It lets customers, partners and Kruzer teams configure an environment, sign in (username/password or Azure AD SSO), select the active tenant and run automation files — the same operations available in the web UI, from a terminal or CI.

Getting Started

Requires Node.js 18 or later.

npm install -g @kruzer/cli
krz configure   # point the CLI at your environment's UI host
krz login       # password or --sso

Commands

Command	Description
krz configure	Set the UI host and discover the backend service URLs
krz login [--sso] [--provider <provider>]	Sign in with username/password or Azure AD SSO
krz auth	Generate a new auth token based on the previous login
krz select tenant	Select the tenant to be active when testing projects
krz run <automation> [-p <params-file>]	Run an automation file

Local state (host, session, tenant) is stored in ~/.config/configstore/krz-cli.json.

Authentication (krz login)

Run krz configure first (sets the host and discovers backend URLs), then sign in.

Username + password (default)

$ krz login
? How do you want to sign in? (Use arrow keys)
  SSO (recommended for corporate users)
❯ Username and password

Pick Username and password and enter your credentials. Nothing changes from previous versions.

SSO (Azure AD)

For corporate users (e.g. Microsoft/Azure AD accounts without a local password):

$ krz login --sso
# or choose "SSO" in the interactive menu
# optionally: krz login --sso --provider microsoft

Run krz configure first. The CLI reads the public SSO settings (Azure AD clientId/tenantId/authority) from the UI host's runtime config (${host}/config.js, the same file the web app uses) — no dedicated endpoint or env var needed.

What happens (OAuth 2.0 Device Authorization Grant, RFC 8628 — the flow az/gh/aws use):

1. The CLI reads the public SSO config from the UI host's config.js.
2. It requests a device code from Microsoft and prints a URL + short code, e.g.:

   To sign in, open https://microsoft.com/devicelogin and enter the code ABCD-1234

3. You open that URL in a browser on any machine and enter the code; Microsoft shows "you can close this tab" when done.
4. Meanwhile the CLI polls Microsoft until you finish, receives the id_token, then calls POST /v1/auth/login-sso to get the Kruzer JWT.
5. The session is stored in ~/.config/configstore/krz-cli.json with authKind: "sso". No credentials are stored.

SSO sessions produce the same Kruzer session/permissions as password login, so krz tenant, krz run and krz configure work the same way. When an SSO session expires, the CLI re-runs the device code sign-in instead of replaying credentials.

Requirements / troubleshooting:

• The client's Azure app registration must have Allow public client flows enabled (Authentication → Advanced settings). No redirect URI registration is needed.
• No local browser is required — works over SSH/headless; just open the printed URL anywhere.
• If a tenant's Conditional Access policy blocks device code flow, sign-in fails — contact the tenant admin.

Build and Test

npm ci
npm run lint           # eslint
npm run format:check   # prettier
npm run build          # tsc
npm run test:unit      # jest unit tests
npm run test:integration  # jest integration tests (device code flow + mocked Microsoft/iam-api)

Release

Publishing to npm is automated by .github/workflows/release.yml. To ship a new version:

git checkout main && git pull
npm version patch          # or minor / major — bumps package.json and creates the vX.Y.Z tag
git push origin main --follow-tags

Pushing the tag triggers the Release workflow, which re-runs lint, format check, build and tests, verifies the tag matches package.json, publishes to the public npm registry (org secret NPM_TOKEN_PUBLISH) and creates the GitHub release.

Contribute

Development happens on kruzer-corp/cli-builder. Open a pull request against main; every PR runs lint, format check, build and the test suites in CI. For bugs or feature requests, open an issue or contact the Kruzer Product Team.