AbuseZero CLI

Install the AbuseZero CLI to run every AbuseZero action from a terminal, a script or CI.

The AbuseZero CLI, the abusezero command, gives you every action that AbuseZero offers to AI apps, from a terminal. It signs in with OAuth and works in the workspace you choose. Every command uses the same envelopes, permission checks and idempotency as the AbuseZero REST API, and every command has a matching tool on the AbuseZero MCP server. Output is JSON by default, so scripts can read it directly. Exit codes are stable, so CI can branch on them.

Install the AbuseZero CLI

Run any command once with npx, or install the command globally. Both need Node.js 22 or later.

npx abusezero --help

npm install -g abusezero

abusezero login

login opens your browser to sign in to AbuseZero. You approve the scopes the CLI asks for. Your role in each workspace still limits what each command can do, as described in member permissions for OAuth.

Command	Description
`abusezero login`	Sign in with your browser.
`abusezero login --device`	Sign in on a machine without a browser. Enter the code it shows on another device.
`abusezero login --machine-client`	Check the machine client set in `ABUSEZERO_CLIENT_ID` and `ABUSEZERO_CLIENT_SECRET`. Nothing is saved.
`abusezero whoami`	Show the sign-in and workspace in use.
`abusezero logout`	Revoke the sign-in and delete it from this computer.

Sign-ins are stored only on your computer, in a file only your account can read. Set ABUSEZERO_CONFIG_DIR to store them somewhere else.

Use the CLI in scripts and CI

For scripts and CI, create a machine client in Developers → Connected apps and set its credentials as environment variables. Every command uses the machine client while they are set, and nothing is written to disk. A machine client belongs to one workspace.

export ABUSEZERO_CLIENT_ID="…"
export ABUSEZERO_CLIENT_SECRET="…"
abusezero login --machine-client

Choose a workspace

A sign-in can reach several workspaces. Choose the one later commands use:

abusezero workspaces list --output table
abusezero workspaces use ws_8a1f3c6e-2d4b-4e9a-b7c5-0f3d6a9e2b81

Machine clients already belong to one workspace, so they skip this step.

Run CLI commands

Commands take the form abusezero <group> <command> [id] [options].

abusezero evaluations list --result deny --days 7 --output table
abusezero evaluations get eval_3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a0c4e93
abusezero access-lists add --kind allow --type email --value jordan@example.com --reason "Verified customer"
abusezero policies create --input policy.json

IDs come after the command, in the order the help shows.
Fields are options in kebab case. For example, the expires_in_days field is --expires-in-days 30.
Booleans are --include-evidence or --no-include-evidence.
Lists repeat the option, or take a JSON array.
Objects take JSON, such as --subject '{"email":"jordan@example.com"}'.
Whole requests come from a file with --input file.json, or from standard input with --input -. Options you also pass override the file's fields.

Run abusezero --help, abusezero <group> --help or abusezero <group> <command> --help to see the commands, options and permission each one needs.

CLI output

Output is JSON by default. Add --output table for a readable table of the main fields. When a list has more results, the table ends with the --cursor option that fetches the next page, as in REST API pagination.

Idempotency keys

Every command that changes data prints its idempotency key to standard error. If the command fails or you aren't sure it finished, run it again with the same key:

abusezero benefits create --input benefit.json --idempotency-key 0b7e4f2a-9c3d-4a1e-8f6b-2d5c7e9a1b30

Permanent actions, such as deleting a benefit or cancelling an import, ask you to confirm by typing the ID, or delete when the command has no ID. In scripts, add --yes. Without it, a permanent action fails in a non-interactive run.

Global CLI options

Option	Description
`--output <json\|table>`	Output format. Defaults to `json`.
`--input <file\|->`	Read the command's input as a JSON object from a file or standard input.
`--idempotency-key <key>`	Reuse a key to retry a change safely.
`--yes`	Confirm a permanent action without asking.
`--help`	Show help for the CLI, a command group or a command.
`--version`	Show the installed version.

CLI exit codes

Code	Meaning
`0`	Success.
`1`	Failure.
`2`	Invalid input, such as an unknown option or a missing ID.
`3`	Sign-in needed.
`4`	Permission denied.
`5`	Not found.
`6`	Conflict.
`7`	Temporarily unavailable. Retry with the same idempotency key.

Errors print to standard error with the error code and request ID, for example Error: Clear the page cursor and try again. (CURSOR_INVALID, request 7d0e5c2a-1f4b-4e8a-b6c3-9a2d5e0f1b74).

CLI environment variables

Variable	Description
`ABUSEZERO_CLIENT_ID`	The machine client's ID. Set it with `ABUSEZERO_CLIENT_SECRET`.
`ABUSEZERO_CLIENT_SECRET`	The machine client's secret.
`ABUSEZERO_CONFIG_DIR`	Where sign-ins are stored.
`ABUSEZERO_API_KEY`	Used only by `abusezero mcp`. A server key the local MCP server uses instead of your sign-in.

CLI command reference

Every command links to the AbuseZero REST API endpoint it calls. The concepts behind each group are in Evaluations, Outcomes, Benefits, Policies and rules, Allow and block lists, Custom identifiers, Browser protection and Bots and AI agents. Imports, exports and data deletions are walked through in Import outcome history and Export and delete data. The Permission column is the command's scope.

Command	What it does	Permission
`workspaces list`	List the workspaces this sign-in can use.	`workspaces:read`
`workspaces use <ws_id>`	Choose the workspace for later commands.	`workspaces:read`
`evaluations create`	Evaluate a claim.	`evaluations:create`
`evaluations preview`	Preview how AbuseZero would evaluate a claim.	`simulations:run`
`evaluations list`	List evaluations, filtered by result, benefit or time.	`evaluations:read`
`evaluations get <id>`	Read an evaluation.	`evaluations:read`
`evaluations graph <id>`	Read the earlier claims linked to an evaluation.	`evaluations:read`
`evaluations evidence <id>`	Read the evidence retained for an evaluation.	`evaluation_evidence:read`
`outcomes report <id>`	Report what happened after an evaluation. `<id>` is the evaluation's ID.	`outcomes:write`
`outcomes list`	List outcomes.	`outcomes:read`
`outcomes get <id>`	Read an outcome.	`outcomes:read`
`simulations run`	Run a benefit's recent claims through a policy, in order, as one sequence.	`simulations:run`
`simulations replay`	Compare recent evaluations with how a saved policy would decide them.	`simulations:run`
`benefits list`	List benefits.	`benefits:read`
`benefits create`	Create a benefit.	`benefits:write`
`benefits get <id>`	Read a benefit.	`benefits:read`
`benefits update <id>`	Update a benefit.	`benefits:write`
`benefits delete <id>`	Delete a benefit. Permanent.	`benefits:write`
`policies list`	List policies.	`policies:read`
`policies create`	Create a custom policy.	`policies:write`
`policies get <id>`	Read a policy.	`policies:read`
`policies update <id>`	Save a new version of a policy.	`policies:write`
`policies duplicate <id>`	Copy a policy.	`policies:write`
`policies delete <id>`	Delete a policy. Permanent.	`policies:write`
`policies versions <id>`	List a policy's versions.	`policies:read`
`policies version <id> <version>`	Read one version of a policy.	`policies:read`
`policies signals`	List the conditions custom rules can use.	`policies:read`
`access-lists list`	List allow and block list entries.	`access_lists:read`
`access-lists add`	Add one or more values to an allow or block list.	`access_lists:write`
`access-lists get <id>`	Read a list entry.	`access_lists:read`
`access-lists delete <id>`	Remove a list entry. Permanent.	`access_lists:write`
`custom-identifiers list`	List custom identifiers.	`custom_identifiers:read`
`custom-identifiers register`	Register a custom identifier.	`custom_identifiers:write`
`custom-identifiers get <id>`	Read a custom identifier.	`custom_identifiers:read`
`custom-identifiers delete <id>`	Delete a custom identifier. Permanent.	`custom_identifiers:write`
`imports list`	List imports.	`imports:read`
`imports create`	Import granted outcomes as JSON.	`imports:write`
`imports create-csv`	Start a CSV import and get its upload address.	`imports:write`
`imports get <id>`	Read an import's progress.	`imports:read`
`imports errors <id>`	Get the error report for an import.	`imports:read`
`imports validate <id>`	Validate an uploaded import.	`imports:write`
`imports confirm <id>`	Confirm a validated import.	`imports:write`
`imports cancel <id>`	Cancel an import and delete its uploaded file and unfinished rows. Permanent.	`imports:write`
`exports list`	List exports.	`exports:read`
`exports create`	Request an export.	`exports:create`
`exports get <id>`	Read an export's status.	`exports:read`
`exports download <id>`	Get a download address for a finished export.	`exports:read`
`data-deletions preview`	Preview what a data deletion would remove.	`data_deletions:write`
`data-deletions create`	Request a data deletion. Permanent.	`data_deletions:write`
`data-deletions list`	List data deletions.	`data_deletions:read`
`data-deletions get <id>`	Read a data deletion's status.	`data_deletions:read`
`analytics get`	Read daily evaluation totals.	`analytics:read`
`request-logs list`	List evaluation requests, including failed ones.	`request_logs:read`
`request-logs get <id>`	Read a request log.	`request_logs:read`
`audit-logs list`	List audit events.	`audit_logs:read`
`audit-logs get <id>`	Read an audit event.	`audit_logs:read`
`browser-collection get`	Read browser setup: sites, issues and recent coverage.	`browser_collection:read`
`browser-collection update`	Update your site list.	`browser_collection:write`
`agents list`	List the AI agents AbuseZero recognizes.	`agents:read`

Each command's fields are the request fields of the REST API endpoint it links to. See REST API, MCP server and CLI coverage for the matching MCP tool of every command.

Run a local MCP server from the CLI

abusezero mcp runs a local MCP server for AI apps that start MCP servers on your computer. See Local MCP server.

Install the AbuseZero CLICopy Anchor Link

Sign in to the CLICopy Anchor Link

Use the CLI in scripts and CICopy Anchor Link

Choose a workspaceCopy Anchor Link

Run CLI commandsCopy Anchor Link

CLI outputCopy Anchor Link

Idempotency keysCopy Anchor Link

Global CLI optionsCopy Anchor Link

CLI exit codesCopy Anchor Link

CLI environment variablesCopy Anchor Link

CLI command referenceCopy Anchor Link

Run a local MCP server from the CLICopy Anchor Link

On this page