CLI

scalaix is the Scalaix command-line tool. It needs Node.js 20 or later.

Install

Run it without installing:

npx scalaix login

Or install the scalaix command:

npm install -g scalaix
scalaix --version

Sign in

scalaix login

This opens your browser. Sign in, pick the team (and optionally the projects) the CLI may use, choose the scopes, and allow. The browser then returns to a page served by the CLI on 127.0.0.1 and the terminal finishes signing in. If the browser doesn't open, copy the URL the CLI prints.

Over SSH or on a machine without a browser, use the device flow:

scalaix login --device

It prints a code and a URL (www.scalaix.com/device). Open the URL on any device, enter the code and approve. The CLI waits until you do.

By default the CLI asks for projects:read projects:write publish usage:read. To manage API keys, add keys:

scalaix login --scope "projects:read projects:write publish usage:read keys"

Check who you are, and sign out (this revokes the tokens on the server and deletes them locally):

scalaix whoami
scalaix logout

Access tokens last an hour and refresh automatically. If the session is revoked (for example from Settings → Connected apps), commands exit with code 3 and ask you to sign in again.

Commands

Projects, collections and endpoints are named by slug: acme, acme/support, acme/support/classify-ticket. Every command accepts --json for machine-readable output, --url to target another Scalaix instance, and --help.

projects, collections, endpoints

scalaix projects
scalaix collections acme
scalaix endpoints acme/support

draft

Drafts an endpoint from a plain-language description. Nothing is saved unless you add --create, which adds the draft to the collection as a new endpoint.

scalaix draft acme/support "Classify a support ticket by category (billing, bug, other) and priority 1-5"
scalaix draft acme/support "Classify a support ticket by category (billing, bug, other) and priority 1-5" --create

--model <id> picks the model that writes the draft. Drafting takes up to a minute or two.

test

Runs an endpoint in the console (the draft, not a published version) and prints the output. The model, tokens, cost and request id go to stderr.

scalaix test acme/support/classify-ticket --inputs '{"ticket": {"subject": "Login", "body": "It fails"}}'
scalaix test acme/support/classify-ticket --inputs @ticket.json
cat ticket.json | scalaix test acme/support/classify-ticket --inputs -

To test a definition that isn't saved yet: scalaix test acme/support --definition @definition.json --inputs @ticket.json.

publish

Publishes a new version of a collection with a changelog.

scalaix publish acme/support -m "Add classify-ticket"

code

Prints code that calls a published endpoint, reading the key from SCALAIX_API_KEY. Languages: curl, python, typescript, javascript, go, ruby, php, java, csharp.

scalaix code acme/support/classify-ticket --lang python
scalaix code acme/support/classify-ticket --lang typescript --out src/classify.ts
scalaix code acme/support --lang python --sdk openai     # gateway setup (OpenAI SDK)

keys

Needs the keys scope. The new key is printed once: store it in your secret manager or environment, not in code.

scalaix keys acme
scalaix keys acme create backend-prod
scalaix keys acme create browser-demo --rules '{"allowed_origins": ["https://demo.acme.com"], "rpm": 30}'

usage and logs

scalaix usage acme --period 7d
scalaix logs acme
scalaix logs acme/support/classify-ticket --status error --limit 50
scalaix logs acme --follow            # polls every 5 s; --interval to change; Ctrl-C to stop

With --json, logs --follow prints one JSON object per line.

chat and models

chat and models call the gateway directly, so they need an sx_ project key rather than your sign-in:

export SCALAIX_API_KEY="sx_..."
scalaix chat "Write a haiku about caching"
scalaix chat "Summarize this" --model auto --system "Answer in one sentence." < notes.txt
scalaix models

chat streams the answer to stdout. --model takes a catalog id, auto or default (the default). Without a key, models lists the catalog through your sign-in.

Use with MCP clients

Clients that support remote MCP servers with OAuth (see MCP) can connect to https://www.scalaix.com/mcp directly. For clients that only run local (stdio) servers, scalaix mcp is a stdio MCP server that forwards every message to https://www.scalaix.com/mcp with your stored sign-in, refreshing it as needed. Sign in once in a terminal, then add it to the client's configuration:

{
  "mcpServers": {
    "scalaix": { "command": "npx", "args": ["-y", "scalaix", "mcp"] }
  }
}

scalaix mcp writes only protocol messages to stdout and logs to stderr. If you aren't signed in, it says so on stderr and exits with code 3.

How the CLI reaches Scalaix

Environment variables

Where credentials live

~/.config/scalaix/credentials.json (or $XDG_CONFIG_HOME/scalaix/credentials.json; on Windows %APPDATA%\scalaix\credentials.json), readable only by you (mode 0600). It holds one entry per base URL: the CLI's client id, the access token and the refresh token. Refresh tokens rotate on every use; the CLI saves the new one before using the new access token, and several scalaix processes share the file safely. scalaix logout revokes and removes the tokens.

Exit codes