@callimacus/auth

The public bootstrap for Callimacus. One callimacus login configures everything a developer needs to build on Callimacus: the private SDK download (~/.npmrc) and API access — with zero prior setup.

This package is intentionally small and public so a new client can run it before they have any credentials. The full operator/tenant-config CLI is the private @callimacus/callimacus-cli, installable only after login configures the registry.

npx @callimacus/auth login

Prefer npx. Both this package and @callimacus/callimacus-cli install a binary named callimacus, so a global install of this one can win the $PATH race and shadow the full tool. Since 1.2.0 the full CLI mounts these same commands, so once it is installed you do not need this package on $PATH at all — callimacus login works from either.

Requires Node.js ≥ 24 (the active LTS). Supported Node lines are the current LTS and newer. The hard technical floor is 22.12.0 — commander v15 is ESM-only and is loaded via require(esm), which Node only supports from 22.12.0 on — but Node 22 is in maintenance and is not a supported target.

First run

npx @callimacus/auth login          # sign in on the hosted page → writes ~/.npmrc + the API profile
npm i -g @callimacus/callimacus-cli # now installs (private, via the configured registry)
callimacus login                    # the full tool carries these commands too, from 1.2.0
callimacus configure …              # …alongside everything else

login signs you in with the same identity as the Studio — passkey, magic code or SSO — on the hosted WorkOS sign-in page: it prints a URL + short code and opens your browser (falling back to "paste this URL" on headless boxes). One sign-in covers every project you belong to, and every one gets a profile (--project <id>, repeatable, narrows it). From 1.7.0 the sign-in itself is kept — no key is minted per project, and a project is entered the first time a command needs it. The registry token goes to user-level ~/.npmrc; the session (your WorkOS refresh token) is stored once per host in ~/.callimacus/config.json, with a profile per project picked that holds no secret — the same file @callimacus/callimacus-cli reads, so this one login configures that CLI too. Each command asks core for a short-lived access token for its project (/cli/token) and caches it for the hour it lives; you act as yourself, with your role in that project, and leaving the organization ends it. The session lasts 30 days (7 idle), then login runs again. The active profile is the first project picked (an already-active one stays active when it is refreshed); callimacus use <project> switches.

An app still needs a key pair of its own, never your session: callimacus scaffold in its directory mints one in the active project and writes it to .env. A browser app takes callimacus scaffold --frontend: only the public key, as VITE_CALLIMACUS_CLIENT_ID, never the secret. CI and callimacus configure keep using key pairs as before.

Core enforces each organization's sign-in policy per project: one that requires SSO or MFA enrolment you have not completed, a parked tenant, or a membership with no role core knows is listed with the reason and the others still land. Sign in to that project in the Studio once, then run login again.

This needs a Callimacus host on a core release that serves /cli/session, /cli/credentials and /cli/token; on a host that predates /cli/token, login says so and npx @callimacus/[email protected] login still mints key pairs. An older host, or one without CLI sign-in enabled, answers that it has no CLI sign-in configured yet, and login says so.

Commands

CI

A developer with several projects has one registry token (machine-level) and one session. In CI, skip the browser:

env:
  CALLIMACUS_NPM_TOKEN: ${{ secrets.CALLIMACUS_NPM_TOKEN }}   # the registry token
steps:
  - run: npx @callimacus/auth setup-ci   # writes ~/.npmrc headlessly
  - run: npm ci

Configuration

Notes

• Config interop: writes ~/.callimacus/config.json in the exact schema @callimacus/callimacus-cli (its lib/config.ts) reads, so the two share one profile.
• SDK env var names: scaffold writes CALLIMACUS_CLIENT_ID / CALLIMACUS_CLIENT_SECRET to .env — the current names the @callimacus/callimacus-sdk env wrapper reads (CALLIMACUS_PUBLIC_KEY/PRIVATE_KEY still work but the SDK logs a deprecation warning).
• No native deps: pure Node + commander and @clack/prompts (≥ Node 24 LTS), so npm i -g / npx work on Windows, Linux, macOS, and WSL. 0600/0700 file modes are enforced on Unix; on Windows they no-op and the files rely on the user-scoped profile dir (same posture as aws/gcloud/gh).