@axtrabase/cli

The axtrabase CLI lets a human or a coding agent inspect an AxtraBase project — schema, permissions, environment — and build against it through the REST API or the public @axtrabase/sdk package, without ever touching Dataverse or Microsoft OAuth directly.

Install

npm install -g @axtrabase/cli
# or, without installing:
npx @axtrabase/cli whoami

If axtrabase --version says command not found right after install, npm's default global prefix likely isn't on your PATH (or isn't writable at all, in which case the install itself silently fails). Fix:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc   # or ~/.bashrc
source ~/.zshrc
npm install -g @axtrabase/cli

Authenticate

axtrabase login

This is a control-plane credential, not a Dataverse or Microsoft credential — the CLI never asks for, stores, or uses Dataverse/Entra secrets. login opens (or prints) a dashboard URL where you generate a CLI token, shown exactly once; paste it back into the terminal prompt (input is masked). The token is stored at ~/.config/axtrabase/credentials.json with 0600 permissions.

axtrabase logout            # remove the local credential only
axtrabase logout --revoke   # also revoke the token on AxtraBase

Non-interactive / CI use

Set AXTRABASE_CLI_TOKEN and skip login entirely — every command reads it first, before the local credential file, and never persists or logs it. Useful for CI and for handing a coding agent a scoped, disposable token.

AXTRABASE_CLI_TOKEN=axcli_... axtrabase context --agent

AXTRABASE_CLI_TOKEN takes precedence over a stored login credential. logout can't unset an environment variable in the shell that invoked it, so instead of falsely claiming "not logged in" it says so explicitly:

$ AXTRABASE_CLI_TOKEN=axcli_... axtrabase logout
Authentication is coming from AXTRABASE_CLI_TOKEN.
Nothing was removed.
Unset the variable in your shell to log out locally:
  bash/zsh:    unset AXTRABASE_CLI_TOKEN
  PowerShell:  Remove-Item Env:AXTRABASE_CLI_TOKEN

--revoke still revokes the active env token server-side (useful for CI/agent cleanup) — it just still can't remove the variable itself.

Select an organisation and project

axtrabase organisations list     # alias: orgs
axtrabase orgs use axtraxia

axtrabase projects list
axtrabase projects use hr-portal

Selection persists to ~/.config/axtrabase/config.json (non-secret — base URL, active org/project). Every project-scoped command after this is concise:

axtrabase tables list

Commands

| Command | What it does | | ---------------------------------------------------- | -------------------------------------------------------------------------------------------- | | login / logout | Authenticate/de-authenticate the CLI. | | whoami | Signed-in user, organisation, active API. | | organisations list / orgs use <org> | Discover and select an organisation. | | projects list / show <project> / use <project> | Discover, inspect, and select a project. | | connection status / verify | The active project's Dataverse connection status; verify re-runs the live readiness check. | | tables list / describe <table> | The Dataverse table catalog, and one table's full column/lookup metadata. | | context [--json\|--agent] | The single most useful command — see below. | | schema export --format json\|typescript | Export table metadata, or generate TypeScript interfaces from it. | | permissions list | Table permission grants (read-only in v1). | | keys list / create / revoke | API key metadata (never the raw key after creation), creation, revocation. | | requests list / get <request-id> | Data-plane request telemetry — the debugging loop. | | events list / get <event-id> / tail | The public Change Feed — list, inspect, and live-tail record changes. | | config list / get / set / unset | Local, non-secret CLI settings. | | docs / openapi | Open developer docs / print the OpenAPI spec. | | status | Fast "am I ready to work" summary — auth, org, project, connection, table/key counts. |

Every command supports -h/--help.

context — the one command to start with

axtrabase context
axtrabase context --json     # the full payload, machine-readable
axtrabase context --agent    # compact, purpose-built for a coding agent

Human output: project, organisation, connection health, table counts, enabled tables (with per-key access if you pass --api-key <id>), whether a usable API key exists, and the SDK/REST entry points. --agent output includes an explicit axtrabase.rules array (use the REST API or the SDK, not Dataverse; keep keys server-side; respect the access field; don't fabricate unresolved metadata).

Exit codes

| Code | Meaning | | ---- | -------------------------------------------------------------- | | 0 | Success | | 1 | Generic failure | | 2 | Authentication required (not logged in, revoked/expired token) | | 3 | Authorization denied | | 4 | Not found | | 5 | Connection not ready | | 6 | Invalid arguments (including "no active project selected") |

--json mode returns { "error": { "code", "message", "requestId"? } } on failure and never mixes a printed error with exit code 0.

Environment variables

| Variable | Purpose | | ------------------------- | -------------------------------------------------------------------------------------- | | AXTRABASE_CLI_TOKEN | Bypasses login/the local credential file. Never persisted or logged. | | AXTRABASE_API_URL | Overrides the API origin (below saved config, above the production default). | | AXTRABASE_DASHBOARD_URL | Overrides where login sends you to generate a token. | | AXTRABASE_PROJECT | Overrides the active project (below an explicit --project flag, above saved config). | | AXTRABASE_CONFIG_DIR | Overrides ~/.config/axtrabase/ — mainly for tests/isolated environments. | | AXTRABASE_API_KEY | A project API key for data-plane commands (events). Never persisted or logged. |

Precedence everywhere it applies: explicit flag > environment variable > saved config > production default.

Full documentation

The complete command reference, agent integration guide, and error model live in docs/cli.md and docs/agents.md.