oidc.pub

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

Quick start

npx oidc.pub login
npx oidc.pub service create --title "My Cluster"
npx oidc.pub service sync \
  --service <service-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.

For a no-login, temporary service that expires within 24 hours:

npx oidc.pub service sync -a --source-url https://issuer.internal --once
npx oidc.pub dev issuer --anonymous

Manage service accounts (Team plan and above) with service-account (aliased to sa):

npx oidc.pub service-account create --name "CI/CD Pipeline" --services "*"
npx oidc.pub service-account list

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

Releases are created from a clean working tree. The release script updates package.json, package-lock.json, and the CLI version in src/main.ts, creates a chore(release): vX.Y.Z commit, pushes the branch, then tags and pushes the tag.

Patch releases are the default path:

npm run release -- patch

Shortcuts are also available:

npm run release:patch
npm run release:minor
npm run release:major

Any npm version argument can be passed through, including prereleases and explicit versions:

npm run release -- prerelease --preid rc
npm run release -- 1.3.0

By default the script pushes to origin and the current branch. Override those with RELEASE_REMOTE and RELEASE_BRANCH when needed:

RELEASE_REMOTE=upstream RELEASE_BRANCH=main npm run release -- patch

Pushing a vX.Y.Z tag triggers the GitLab pipeline. The pipeline typechecks, builds the CLI, publishes Docker images, and publishes both npm packages (oidc.pub and @oidc.pub/cli) using npm 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=<service-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=<service-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=<service-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-9sfs) | | 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.