Drive Ajolla from the terminal — log in, sync, regenerate, read usage.

The CLI is published on npm as @ajolla/cli. Install it globally for interactive use, or as a dev dependency for CI:

bash
# global, for interactive use
npm install -g @ajolla/cli

# project-local, for CI
npm install --save-dev @ajolla/cli
npx ajolla --version

Node.js 18+ is required. The CLI has zero runtime dependencies beyond Node’s built-ins and one unzip helper.

1. 01

   Mint a token in the dashboard

   Open /settings#cli-tokens and click Create token. Tokens are shown once at creation; the dashboard stores only a hash so a leaked token cannot be recovered from our database.

   Give the token a name that describes where it will live (e.g. “ci-prod”, “laptop-personal”). Naming helps you revoke the right one when a machine is decommissioned.

2. 02

   Save the token locally

   bash
   ajolla login --token=ajol_xxxxxxxxxxxx

   The token is written to ~/.ajolla/config.json with mode 0600. The login command calls /api/cli/me to validate the token before saving — bad tokens never touch disk.

3. 03

   Or pass auth per command

   For CI, prefer environment variables over a stored config file. Precedence (highest first): explicit --token= flag, then $AJOLLA_TOKEN, then ~/.ajolla/config.json.

   bash
   AJOLLA_TOKEN=ajol_xxxx ajolla sync

login

Validate a token, then persist it + the API base URL to ~/.ajolla/config.json.

init

Write ./ajolla.json — the project-local manifest that lists which artifacts to sync.

sync

Pull every artifact listed in ./ajolla.json. The right command for CI.

pull

Download one artifact by slug + kind. Useful for one-off inspection.

generate

Trigger a server-side regeneration. With --watch, polls each job to completion.

usage

Print plan tier, billing period, and quota usage for projects + generations + MCP requests.

1. 01

   Declare what to sync

   bash
   ajolla init --project=petstore --kinds=ts,mcp,docs --out=./vendor

   This writes a manifest to ./ajolla.json. Aliases are accepted (ts, py, go, rb, java, cs, php, mcp) and expanded to canonical kind names in the file.

   json
   {
     "project": "petstore",
     "artifacts": [
       { "kind": "typescript-sdk", "out": "./vendor/typescript-sdk" },
       { "kind": "mcp-server",     "out": "./vendor/mcp-server" },
       { "kind": "docs",           "out": "./vendor/docs" }
     ]
   }

   Check this file into the consuming repo — it’s the contract between Ajolla and your build.

2. 02

   Sync in CI

   bash
   # .github/workflows/sync-sdk.yml step
   - run: npx ajolla sync
     env:
       AJOLLA_TOKEN: ${{ secrets.AJOLLA_TOKEN }}

   sync runs the pull flow for every artifact in the manifest. It aborts on the first failure, so a stale or missing generation will turn the build red — which is usually what you want.

3. 03

   Trigger a fresh build

   sync downloads whatever artifact is already on the server. To kick off a regeneration first — useful after a spec change — use generate:

   bash
   ajolla generate --project=petstore --kinds=ts,mcp --watch

   With --watch, the CLI polls each generation to a terminal state (succeeded or failed) with a 5-minute cap per job.

4. 04

   Check your quota

   bash
   ajolla usage

   Prints the current plan tier, the calendar-month billing period, and a usage bar for each metered dimension: projects, generations, and hosted MCP requests. Pass --json to get a machine-readable payload.

Every gate the dashboard enforces, the CLI enforces too. If you exceed your plan’s monthly generation cap, the server returns HTTP 402 with a structured payload (plan slug, used, limit) so the CLI can print a clean error rather than a stack trace.

projects

Max active projects you can own. Hard-gated on create.

generations / month

Sum of SDK + MCP generation jobs in the current calendar month. Hard-gated.

mcpRequests / month

Hosted MCP invocations in the current calendar month. Tracked and surfaced; per-project rate limiting (120 req/min) is the real abuse shield.

AJOLLA_TOKEN

Bearer token minted in /settings#cli-tokens. Overridden by an explicit --token=flag.

AJOLLA_API

API base URL. Defaults to https://ajolla.dev. Override when targeting a self-hosted install.

401 from any command

Token was revoked or never minted. Re-run `ajolla login` or refresh the CI secret.

402 from generate

Monthly generation quota hit. Run `ajolla usage` to see exact numbers; upgrade in /settings/billing.

404 from pull

Project slug or artifact kind is wrong, or the artifact has never been generated for that project. Run `ajolla generate` first.

Download timeout

Artifact URLs are signed for 60 seconds. The CLI re-mints a URL per command, so a timeout is usually network-side.

Stuck in `running`

--watch caps each poll at 5 minutes. If you hit it, check /projects/<slug> in the dashboard; the row will show the failure reason.

• Store AJOLLA_TOKEN as a repository secret. Never commit it.
• Run `ajolla sync` after the build that needs the SDK starts. Generated files are not in version control — sync recreates them.
• Treat the manifest (ajolla.json) as source of truth. Reviewing a change to it should be as careful as reviewing a Dockerfile.
• Pair `generate` with `sync` only when a spec change must propagate immediately. For normal CI runs, `sync` alone is enough — generations are triggered when you upload a new spec.
• If the same SDK is shipped to multiple downstream repos, mint a separate CLI token per repo so you can revoke them independently.

• Getting started — Sign in to first generated zip in one session.
• OpenAPI readiness — Inputs the CLI's outputs depend on.
• Shipping SDKs and MCP servers — The release checklist for each artifact you sync.