@odla-ai/cli

⚠️ Early access — pre-1.0. Agents work from bounded runbooks; humans approve credentials, production changes, releases, and merges. APIs and exact package availability can change. Review the documented guarantees and limitations; this software is MIT-licensed and provided without warranty.

Project-neutral provisioning CLI for odla apps. It creates and validates an odla.config.mjs, then uses that config to register an app, enable services, push odla-db schema/rules, configure per-app BYOK AI, configure Clerk auth, record deployment links, connect read-only Google Calendar mirrors, provision o11y ingest credentials, and transfer local or deployed Worker secrets without printing them. It also gives platform admins a scoped System AI control surface and gives app owners a provider-key-free hosted security command.

It does not know about any specific app. App identity, environments, services, schema, rules, auth, AI provider, and links all come from config.

Install

No install needed — the package ships a single odla-ai binary, so npx can run it directly:

npx @odla-ai/cli init --app-id my-app --name "My App"

For a project you keep working in, install it as a dev dependency so the shorter npx odla-ai form works and the version is pinned by your lockfile:

npm view @odla-ai/[email protected] version
npm i -D --save-exact @odla-ai/[email protected]

Prerequisites

• Node.js 20 or newer (node --version).
• An existing odla account that has signed in at least once. For any command that may need a fresh device grant, pass --email <account> or set ODLA_USER_EMAIL. This value identifies who may review the request; it is not a password or session credential, and an agent must never ask for either.
• odla apps usually deploy as Cloudflare Workers. If you have never used Cloudflare:
  1. Create a free account at https://dash.cloudflare.com/sign-up.
  2. You do not need to install anything: npx wrangler login opens the browser once to link your account, npx wrangler dev runs a Worker locally, and npx wrangler deploy ships it.
  3. The .dev.vars file this CLI writes with provision --write-dev-vars is wrangler's local secrets file — wrangler dev picks it up automatically. It is chmod 0600 and gitignored; never commit it or paste its contents into wrangler.toml.

Commands

npx odla-ai setup
npx odla-ai init --app-id my-app --name "My App"
npx odla-ai doctor
npx odla-ai calendar status --env dev
npx odla-ai calendar calendars --env dev
npx odla-ai calendar connect --env dev
npx odla-ai calendar resync --env dev
npx odla-ai calendar disconnect --env dev --yes
npx odla-ai capabilities --json
# install SDKs, write the Worker, and create wrangler.jsonc before secret push
npx odla-ai provision --dry-run
npx odla-ai provision --email [email protected] --write-dev-vars --push-secrets
npx odla-ai smoke --env dev
npx odla-ai secrets push --env dev
npx odla-ai secrets set clerk_webhook_secret --env dev --stdin
npx odla-ai secrets set-clerk-key --env dev --from-env CLERK_SECRET_KEY
npx odla-ai security run . --env dev --ack-redacted-source
npx odla-ai security github connect --env dev # infers owner/name from git origin
npx odla-ai security plan --env dev
npx odla-ai security sources --env dev
npx odla-ai security run --source <source-id> --ref main --env dev --plan-digest <digest-from-security-plan> --ack-redacted-source
npx odla-ai security status <job-id>
npx odla-ai security report <job-id>
npx odla-ai admin ai show --email [email protected]
npx odla-ai admin ai models
npx odla-ai admin ai set security --discovery-provider anthropic --discovery-model claude-opus-4-8 --validation-provider openai --validation-model gpt-5.5 --enabled
npx odla-ai admin ai credentials
npx odla-ai admin ai credential set anthropic --from-env ANTHROPIC_API_KEY
npx odla-ai admin ai usage --app-id my-app --env prod --limit 50
npx odla-ai admin ai audit --limit 25
npx odla-ai skill install
npx odla-ai version

init writes:

• odla.config.mjs
• src/odla/schema.mjs
• src/odla/rules.mjs
• .gitignore entries for local credentials

New configs contain only the dev environment. Add prod explicitly after the development flow is healthy; provision refuses to mutate prod or production without --yes and supports --dry-run for review.

provision performs the standard safe setup flow:

When using --push-secrets, create the Worker and its Wrangler config first. The CLI checks that config and wrangler whoami before it issues or rotates a shown-once credential.

1. Gets an odla_dev_... token by email-bound device handshake, or reuses ODLA_DEV_TOKEN / .odla/dev-token.json. A fresh handshake requires --email <account> or ODLA_USER_EMAIL; the matching existing account must sign in, review the exact code, and approve it. Opening the URL alone does not claim the request. When the code is displayed it opens the approval page in your browser — including from scripted and agent-driven shells; only CI, SSH sessions, and display-less hosts skip the launch. Pass --open to force it anyway, or --no-open to suppress it. Browser launch is best-effort; the printed URL and code always remain the fallback.
2. Creates the platform app if needed.
3. Enables configured services in every configured environment. Calendar config is normalized per env and fixed to Google read-only access.
4. Mints or reuses each env's configured service credentials: an odla-db app key for db and an ingest token for o11y.
5. Pushes the configured schema and rules.
6. Configures platform AI and stores provider keys in the tenant vault when the configured key env var is set.
7. For calendar, reads owner-visible connection status and, when needed, asks the platform for a state-bound Google authorization URL and opens only the exact Google OAuth endpoint (or a same-platform interstitial). The human completes consent there; provision follows the exact attempt through initial sync. OAuth codes and refresh tokens never enter the CLI, repo, chat, or app.
8. Writes .odla/credentials.local.json with mode 0600.
9. With --write-dev-vars, writes the local Worker values to .dev.vars; with --push-secrets, transfers the configured service secrets to the matching deployed Worker environment over Wrangler stdin.

Plain reruns are idempotent. Pass --rotate-o11y-token only when deliberately invalidating and replacing the o11y token; combine it with --push-secrets so the replacement reaches the Worker in the same run. --rotate-keys remains the broader credential rotation. Production mutation or secret transfer requires --yes. Pass --no-write-credentials to skip writing the local credentials file; it cannot be combined with an operation that would issue a shown-once credential.

Rotation and Wrangler secret replacement are not a distributed transaction. The CLI preflights Wrangler first and persists the replacement before pushing; if that final push still fails, follow the printed secrets push --env ... retry. Do not run the rotation flag again.

Device-grant security and recovery

The account email sent during a fresh handshake is a non-secret identity hint, not proof of identity. Unknown or never-signed-in accounts never produce a claimable Studio request, and the public start/poll shape intentionally does not reveal whether an account exists. The signed-in matching user must explicitly review the exact code before it becomes pending, and only one claimed pending or approved-but-uncollected request can be active for that user.

Developer grants are tracked by id, owner, label, scopes, creation/expiry, last use, and revocation state. The plaintext token is delivered once to the polling client and is never available from the inventory. Every signed-in user can inspect and revoke their own grants under Your agent credentials in Studio; platform admins additionally see the global token inventory and metadata-only attempt evidence. Future requests with a revoked token fail. Deleting .odla/dev-token.json or .odla/admin-token.local.json removes the local copy but does not revoke a token already copied elsewhere, so use Studio revocation when compromise or accidental approval is possible.

smoke verifies a provisioned environment from local credentials. It fetches the platform public config, checks the configured AI provider, fetches the live odla-db schema with the tenant key, compares expected schema entities, and runs a count aggregate against the first entity. It fails early with a clear message when provisioning has not written .odla/credentials.local.json.

Read-only Google Calendar

Calendar is a platform-custodied connector, not a Google credential stored by the application. Enable both db and calendar, configure calendar ids per environment, then run normal provision. The first run has two distinct human checkpoints: the odla device code establishes app-owner authority, and the subsequent server-issued Google page grants calendar.events.readonly consent.

For parity with a static Google Appointment Schedule embed/link, set the public bookingPageUrl per environment. Provision applies it through the owner-only calendar settings route; it is public configuration, not a credential.

calendar status returns the safe connection/sync projection; add --json for agent automation. Once connected, calendar calendars lists ids visible to the Google identity so the checked-in selection can be refined. calendar connect applies the checked-in booking-page setting and starts consent when the connection is absent, failed, disconnected, or degraded (so an agent can repair revoked credentials); a healthy connection is reused. A needs_sync connection already has provider credentials, so connect/provision resyncs it without requesting Google consent again; an existing authorization or initial sync is awaited instead of creating a duplicate attempt. calendar resync asks the hosted connector to sync immediately; calendar disconnect --yes stops watches and deletes this app/environment connection's encrypted platform token and cursors without purging retained mirror rows, which may therefore remain readable but stale. It does not revoke the shared user-to-Google-OAuth-project grant, because that could invalidate other odla connections for the same user. A future explicitly global revoke command would need cross-connection accounting and warning. Production resync requires --yes, as does a direct production connect. None of these commands accepts a Google authorization code, client secret, access token, or refresh token.

The SDK uses the existing server-side db values (ODLA_ENDPOINT, ODLA_TENANT, ODLA_API_KEY), so calendar adds no Worker secret. Never expose ODLA_API_KEY to a browser. Trusted Worker code can initialize @odla-ai/calendar; browser code reads $bookings through @odla-ai/db/client under explicit rules or imports pure helpers from @odla-ai/calendar/client.

These commands operate the current read/embed reconciliation slice. The CLI has no native slot-picker or create/reschedule/cancel command, and exposes no rolling-window/age-out, quota-backoff, retention/purge, or provider-derived mutation-id control. Public health remains aggregate rather than per calendar.

The bundled build/migration skills add a passive pre-ship gate with @odla-ai/security: after the exact-version availability check, run npm i -D --save-exact @odla-ai/[email protected], then npx odla-security scan . --profile odla --out .odla/security/pre-ship --fail-on high --fail-on-candidates critical. The passive scan remains a separate binary: it makes no model calls and does not execute target code. After explicit redacted-source approval, odla-ai security run . --env dev --ack-redacted-source adds hosted discovery and independent validation. The CLI obtains/reuses app-owner auth and the platform supplies bounded role grants; it never requests provider keys. The hosted run accounts for both immutable role ceilings: discovery reserves one call for recon, caps first-pass hunts to what remains, and uses only residual calls for retries; validation reviews the highest-risk candidates first. The console and artifacts show used/skipped calls, and a budget-limited run is incomplete unless explicitly reviewed with --allow-incomplete. All hosted-security network calls target the configured odla platform origin (/registry/security/runs, /registry/ai/extract, and completion). The CLI never contacts a model-provider host; the odla.ai broker alone owns the typed security prompts/schemas and resolves the admin-selected route and vaulted credential. A cached or environment token is audience-bound and is never sent to a different --platform origin. Early-access run ceilings are rolling. A platform-ceiling 429 always carries a conservative Retry-After. A provider-side 429 uses the sanitized provider_rate_limited code after the provider SDK's bounded retries and carries a bounded Retry-After only when the upstream supplied one. The CLI does not echo arbitrary response text or silently change the admin-selected model. Before installing the exact release, require npm view @odla-ai/[email protected] version to succeed before installation. An exact-version E404 means the release is unavailable, not that the security preflight passed, and does not prove the package name is absent. odla's own engineering environment uses an equivalent internal gate; customer projects should use the published odla-security command above.

For a server-side, commit-pinned review, connect one repository through the source-read-only odla GitHub App. The CLI infers owner/name from a safe GitHub HTTPS or SSH origin; pass --repo owner/name when it cannot. It opens GitHub's installation/authorization page and polls that exact odla attempt:

npx odla-ai security github connect --env dev
npx odla-ai security plan --env dev
npx odla-ai security sources --env dev
npx odla-ai security run --source <source-id> --ref main --env dev --plan-digest <digest-from-security-plan> --ack-redacted-source

security plan is the owner-readable disclosure preflight. It shows the exact admin-selected discovery and validation provider/model, immutable policy versions, per-route call/input/output bounds, prompt bundle, redaction/report contracts, credential readiness, provider independence, report retention, the no-target-execution boundary, and a digest covering that complete processing contract. security sources includes the same plan (and returns { plan, sources } with --json). A source run fetches it again and refuses to enqueue while either route is disabled, lacks a usable platform credential, or is not independently routed. Copy the displayed digest into --plan-digest; the CLI requires it in addition to --ack-redacted-source and refuses to let a generic acknowledgement silently approve a refetched plan. The enqueue request carries the plan digest and both expected policy versions. After verifying the user-supplied plan digest, the CLI fetches and prints odla.ai's exact source/ref/profile execution intent. A second server-computed digest binds that selection, the redacted disclosure, and the plan digest; the CLI sends it as expectedExecutionDigest. A concurrent selection or admin change returns intent_conflict, plan_conflict, policy_conflict, or security_ai_not_ready instead of silently switching providers or models. Fetch and review a fresh security plan, then explicitly acknowledge its new digest. An omitted --ref is previewed as the source's explicit current default-branch name. If that default changes before enqueue, odla.ai rejects the stale intent; it never defers the choice to GitHub HEAD at Workflow execution time.

The source job defaults to follow, renders the normalized report, and applies the same --fail-on high, --fail-on-candidates critical, and incomplete coverage gate; use --no-follow only to enqueue. security status <job-id> and security report <job-id> recover or inspect a prior job. security github disconnect --source <source-id> --env dev --yes revokes odla's saved source without requiring a GitHub-side uninstall.

The client sends only the opaque odla sourceId, ref, profile, and explicit sourceDisclosure: "redacted"; it has no PAT, GitHub installation id, provider key, provider, or model flag. odla.ai verifies repository access, resolves the ref to an immutable commit SHA, fetches the bounded snapshot server-side, and routes bounded best-effort credential-pattern-redacted snippets through the admin-selected System AI discovery and independent-validation models. GitHub read authorization is not source disclosure consent, which is why --ack-redacted-source remains required. The retained schema has no archive, file-body, explicit source-excerpt, context packet, raw provider-response, execution-trace, or reproduction-output field. The private normalized report does retain bounded best-effort credential-pattern-redacted model-derived prose and repository-relative paths for up to 90 days, so treat it as sensitive because that prose can reveal source semantics or an unrecognized secret. GitHub and provider retention/residency terms remain separate. GitHub Checks contain counts/coverage and link to the authenticated Studio report. Target code is not executed, and even complete coverage is not proof of security; unscheduled, shallow, blocked, budget-exhausted, and projection- truncated work stays visible.

admin ai show|models|set|credentials|credential set|usage|audit manages platform-funded System AI (o11y.triage, security.discovery, security.validation). It uses a separate, mode-0600 .odla/admin-token.local.json cache. Studio displays the exact scope, only an admin can approve it, and it expires after ~15 minutes; policy, credential, and usage capabilities are separate and cannot act as the approver on ordinary app/db/o11y routes. admin ai models reads the server catalog. admin ai set security updates discovery and independent validation together with expected revisions; a concurrent edit returns 409 and reloads instead of being overwritten. admin ai usage requests its own read-only capability and lists metadata-only events and status aggregates; narrow it with --app-id, --env, --run-id, and --limit, or use --json for automation. admin ai audit separately reads immutable metadata-only policy and credential change events with actor attribution; credential values never enter that trail. It never returns prompts, repository source, model output, reports, or provider credentials. Credential writes accept only --from-env <NAME> or --stdin and never place the value in argv, output, or the cache. System AI and each app's BYOK AI are separate vault/funding paths. Discovery and validation provider/model settings are authoritative server policy: a security command has no field that can override either route. Admin bounds can only narrow the hard ceilings of 64 calls per role/run and, for each call, 512 KiB input and 32,768 output tokens. For a non-default platform, environment credentials must also declare the matching ODLA_ADMIN_TOKEN_AUDIENCE.

secrets push --env <env> is the narrower recovery/retry command. It moves the configured env's odla-db key and/or o11y ingest token from .odla/credentials.local.json into the deployed Worker by piping each value over stdin to wrangler secret put; values never appear on argv, in output, or in an agent's transcript. It preflights wrangler whoami and the presence of a wrangler config file. The env prod/production targets the top-level wrangler environment (no --env flag is passed to Wrangler) and requires --yes; every other env maps to wrangler --env <name>. --dry-run prints a redacted plan without spawning anything. For the normal path, use provision --write-dev-vars --push-secrets so service enablement, credential issuance, local config, and deployed secret transfer stay one composition.

secrets set <name> --env <env> stores one named secret in that env's tenant vault — the same write-only slot Studio's Secrets panel fills (for example clerk_webhook_secret for synced auth). The value may come only from --from-env <NAME> or --stdin, so a producer command pipes straight into the vault without the secret ever appearing on argv, in output, or in an agent's transcript; it is encrypted at rest and readable back only by that tenant's app API key, never by the CLI, Studio, or the developer token. $-prefixed names are platform-reserved. secrets set-clerk-key --env <env> stores the app's Clerk secret key in the reserved $clerk_secret slot so the platform can resolve the app's users (invites, member lookups); reserved secrets are never readable by app keys. It refuses an sk_test_ key for a prod-named env and requires --yes to put an sk_live_ key into a non-prod env, since live users would sync into a non-prod tenant. Both commands authenticate with the developer token ($ODLA_DEV_TOKEN, the cached token, or a fresh device approval), and prod-named envs require --yes, matching secrets push.

Who does what

If a change is deterministic from odla.config.mjs, the CLI owns it: app and service enablement, credential issuance and local persistence, .dev.vars, schema/rules/auth/AI/calendar configuration, owner-safe consent orchestration, and Wrangler secret transfer. The coding agent owns application semantics: installing @odla-ai/o11y, wrapping the Worker with withObservability, and choosing useful spans, metrics, errors, and LLM-usage records. The human owns the device approval, production consent, and explicit destructive rotation. Studio is where people view telemetry and perform manual recovery, configure System AI, and inspect app/run-attributed platform usage; its o11y token control is not the normal setup path. Run npx odla-ai capabilities for the human-readable contract or add --json when an agent or tool needs to branch on it without scraping prose.

setup (and skill install) installs one complete offline runbook bundle at .agents/skills/, then adds thin native adapters for Claude Code (.claude/skills/), Codex, Cursor (.cursor/rules/), GitHub Copilot (.github/copilot-instructions.md), Gemini CLI (GEMINI.md), and portable AGENTS.md agents. The default is --agent all; select one or more with --agent claude,codex or repeated --agent flags. A global install supports the native Claude and Codex roots only.

Existing AGENTS.md, GEMINI.md, and Copilot instructions are preserved. The installer appends a bounded odla-managed section, is idempotent, refuses symlink-redirection and locally changed managed content, and lets --force replace only odla-owned content. The local bundle includes build, migration, and observability-debug procedures plus every reference they need; agents do not need online docs or access to odla's private service source after setup.

After running setup, the whole prompt can be: “Set up odla in this repo using the installed local odla runbook. Decide whether this is a new app or an existing site to migrate, then drive it end to end. Ask me only for the device approval and other human-only checkpoints.”

For programmatic callers, installSkill() keeps targetDir, written, and unchanged as one unambiguous primary-root view: the latter two contain paths relative to targetDir only. Use the additive absolute writtenPaths and unchangedPaths fields to inspect every shared-bundle and adapter artifact.

doctor also lints for common footguns: permission rules that are literally "true" (public writes always warn; a public view warns unless the namespace is listed in db.publicRead), schema entities missing from the rules map, credential files (.dev.vars, .odla/*) tracked by git, a wrangler assets directory pointed at the project root or at a directory containing node_modules (the wrangler dev "spawn EBADF" footgun), secret-shaped values in wrangler vars, and a package.json script literally named deploy (CI may auto-deploy it).

Config

export default {
  platformUrl: process.env.ODLA_PLATFORM_URL ?? "https://odla.ai",
  dbEndpoint: process.env.ODLA_ENDPOINT ?? process.env.ODLA_DB_ENDPOINT ?? "https://db.odla.ai",
  app: { id: "my-app", name: "My App" },
  envs: ["dev"], // add "prod" deliberately; provisioning it requires --yes
  services: ["db", "ai", "o11y", "calendar"],
  db: {
    schema: "./src/odla/schema.mjs",
    rules: "./src/odla/rules.mjs",
    defaultRules: "deny",
    publicRead: [], // namespaces where a `view: "true"` rule is intentional
  },
  ai: {
    provider: process.env.ODLA_AI_PROVIDER ?? "anthropic",
    keyEnv: "ANTHROPIC_API_KEY",
  },
  calendar: {
    google: {
      calendars: { dev: ["primary"] },
      bookingPageUrl: {
        dev: "https://calendar.google.com/calendar/appointments/schedules/…",
      },
      match: {
        summaryPrefix: "Intro", // optional
        organizerSelf: true,    // default true
        requireAttendees: true, // default true
      },
      attendeePolicy: "full", // or "hashed"
      // This CLI release always requests calendar.events.readonly.
    },
  },
  auth: {
    // Publishable key (public). Created + pulled by the Clerk CLI (`npx clerk`);
    // See the installed odla-migrate phase 3. Inline `pk_…` or "$ENV_VAR".
    clerk: {
      dev: "$CLERK_PUBLISHABLE_KEY",
      prod: "$CLERK_PUBLISHABLE_KEY",
    },
  },
  links: {
    dev: "https://dev.example.com",
    prod: "https://example.com",
  },
};

db.schema and db.rules may be inline objects, JSON files, or JS modules exporting default, schema / SCHEMA, or rules / RULES.

If schema is present and rules are omitted, defaultRules: "deny" generates deny-all rules for every schema entity. That is the safe default for Workers that mediate reads and writes with an app key.