AX

AX is the command-line interface for Abbit Platform. Use it to work with Tracker and Wiki, or connect an MCP client through local stdio.

Requires macOS and Node.js >=24.15.0 <25.

Install

Install from npm:

npm install --global @abbit/ax@latest
ax --version

The same executable is available as abbit-ax if another program already uses ax on your PATH.

Log in

ax login
ax status

Browser login opens an authorization page. Select your workspace and approve access. The browser must be able to reach the machine running AX.

For headless use, sign in with an existing personal or service API key. Enter it at the hidden prompt or pass it through stdin:

ax login --key
ax login --key < /secure/path/key

Never pass a key as a command argument. ax logout signs out of the selected workspace. For API keys, it removes only the local copy; revoke the key in Abbit to invalidate other copies.

Select a project workspace

ax context init
ax context set --tracker-id <tracker-id>
ax context show

One saved workspace is selected automatically. With multiple saved workspaces, bind the project using context init or pass --workspace <id> for a single command. ax login --local logs in and binds the project together; plain login only saves the login.

Use commands

ax tracker current item list
ax tracker current item <item-id> comment add --input.body 'An update'
ax beta wiki <wiki-id> search 'authentication'
ax catalog refresh
ax --help

Commands and flags come from the tools available through Abbit MCP. Help uses the cached command catalog; catalog refresh updates it.

Flag values are explicit, including booleans: --input.enabled=false. Use --args-json '{...}' or --args-file <path> for complex values, preserving the tool's JSON field names. --args-file - reads stdin. Duplicate or overlapping inputs are rejected.

Commands return one page of results. When a mutation accepts an idempotency key, AX generates one if omitted and reports the effective key. If the outcome is unknown, inspect the remote state before retrying and reuse that key.

Scripts and MCP clients

Add --json for machine-readable output. The version-1 envelope preserves the MCP result and reports effective idempotency keys in client.idempotencyKey. Exit codes are 0 for success, 2 for local input or configuration errors, and 1 for execution failures.

To connect an MCP client, configure command ax with arguments ["mcp", "serve"]. Sign in first and use --workspace <id> when the client needs an explicit workspace:

ax --workspace <id> mcp serve

Stdio stdout is reserved for MCP protocol messages.

Shell completion

Activate completion in your shell:

# Bash
source <(ax completion bash)

# Zsh
source <(ax completion zsh)

Completion uses the local command cache and works offline. Run ax catalog refresh to update it. AX does not edit your shell startup files.

Attachments

Use Tracker commands to initiate, complete and publish uploads. Transfer the file bytes with:

ax attachment upload --tracker-id current --item-id <id> --upload-id <id> --file ./attachment.pdf
ax attachment download --tracker-id current --item-id <id> --attachment-id <id> --file ./download.pdf

Uploads accept regular files up to 25 MiB. Downloads verify size and checksum and never overwrite an existing file. The transfer commands do not complete or publish uploads automatically.

Troubleshooting

• For a missing or expired login, run ax login for the intended workspace.
• If login --local saves the login but cannot bind the project, fix the reported context error and run ax context init --workspace <id>.
• If a crash leaves a context or cache .lock file, confirm no AX process is writing that file before removing the stale lock and retrying.
• AX and the standalone abbit-mcp command use separate credential stores and require separate logins. Do not copy credentials between them.