@oidc.pub/cli

CLI for oidc.pub — log in, create services, and sync OIDC configuration.

Quick start

npx @oidc.pub/cli login
npx @oidc.pub/cli service create --name "My Cluster"
npx @oidc.pub/cli service sync \
  --service <your-subdomain> \
  --source-url https://your-issuer.internal

For staging, also pass --oidcpub-url https://staging.oidc.pub. If the source issuer uses a self-signed or otherwise untrusted certificate, add --insecure-tls-verify-skip.

Local development

Run the CLI directly from source without building:

npm install
npm run dev -- --help
npm run dev -- login
npm run dev -- service sync --help

Releasing

Create a release commit, tag it, and push both with:

npm run release -- patch

Shortcuts for minor and major bumps are available via npm run release:minor and npm run release:major. Pushing a v* tag triggers the GitLab pipeline to publish the package to npm using trusted publishing.

Docker

Two image tags are published:

• registry.gitlab.com/oidc.pub/cli:latest — full CLI (interactive commands, sync, etc.)
• registry.gitlab.com/oidc.pub/cli:latest-sync — runs service sync automatically, for Docker/K8s deployments

Sync worker (Docker)

docker run -d --name oidcpub-sync \
  -e OIDC_SOURCE_URL=https://your-issuer.internal \
  -e OIDCPUB_SERVICE_ID=<your-subdomain> \
  -e OIDCPUB_API_KEY=<your-api-key> \
  registry.gitlab.com/oidc.pub/cli:latest-sync

Sync worker (Kubernetes)

When running inside a Kubernetes cluster, the worker auto-detects the API server address — no OIDC_SOURCE_URL needed.

kubectl run oidcpub-sync \
  --namespace=kube-system \
  --image=registry.gitlab.com/oidc.pub/cli:latest-sync \
  --env="OIDCPUB_SERVICE_ID=<your-subdomain>" \
  --env="OIDCPUB_API_KEY=<your-api-key>"

One-shot mode

Pass --once to sync a single time and exit. One-shot mode is also enabled automatically when CI=true is set in the environment, which most CI/CD systems do by default.

docker run --rm \
  -e OIDC_SOURCE_URL=https://your-issuer.internal \
  -e OIDCPUB_SERVICE_ID=<your-subdomain> \
  -e OIDCPUB_API_KEY=<your-api-key> \
  registry.gitlab.com/oidc.pub/cli:latest-sync \
  --once \
  --insecure-tls-verify-skip

Environment variables

| Variable | Required | Default | Description | |---|---|---|---| | OIDCPUB_SERVICE_ID | Yes | — | Your oidc.pub service subdomain (e.g. myapp) | | OIDCPUB_API_KEY | One of key/token | — | Static API key from the dashboard | | OIDCPUB_OIDC_TOKEN_PATH | One of key/token | — | Path to an OIDC token file | | OIDC_SOURCE_URL | No* | — | Base URL to fetch OIDC config from. *Auto-detected in Kubernetes. | | SYNC_INTERVAL | No | 300 | Seconds between syncs | | OIDCPUB_SERVICE_URL | No | https://oidc.pub | oidc.pub base URL. Set this to https://staging.oidc.pub when using staging. | | CI | No | — | When true, enables one-shot mode automatically |

Building

docker build --target cli -t oidc-pub-cli .
docker build --target sync -t oidc-pub-cli-sync .

The multi-stage Dockerfile compiles TypeScript via esbuild and produces a minimal image (~55 MB) with no node_modules.