@axtrabase/cli

@axtrabase/cli

The axtrabase CLI lets a human or a coding agent inspect an AxtraBase project — schema, permissions, environment — and build against it through @axtrabase/sdk or the REST API, 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.
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 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.

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.