npm package: @oidc.pub/cli
Description: CLI for oidc.pub to log in, create services, and sync OIDC configuration.
Latest version: 1.2.4

# @oidc.pub/cli

CLI for [oidc.pub](https://oidc.pub) — log in, create services, and sync OIDC configuration.

## Quick start

```bash
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:

```bash
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:

```bash
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)

```bash
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.

```bash
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.

```bash
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

```bash
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`.