Arkveil
CLI

Command reference

Full reference for every arkveil CLI command, grouped by resource.

This page covers every resource the CLI manages. See Authentication for auth/keys, and Configuration for global flags, JSON output, and exit codes.

health

arkveil health

Connectivity check against the configured base URL.

tags

arkveil tags list
arkveil tags get <id>
arkveil tags create --slug pii --color '#e11' [--tooltip <t>] [--description <d>]
arkveil tags update <id> --color '#f00' [--tooltip <t>] [--description <d>]
arkveil tags delete <id> [--yes]

trees

Read-only navigation trees:

arkveil trees all
arkveil trees tests
arkveil trees datasources
arkveil trees data-policies
arkveil trees actions
arkveil trees action-policies

folders

arkveil folders create --parent <id> --title <t> [--description <d>]
arkveil folders update <folderId> --title <t> [--description <d>]
arkveil folders delete <folderId> [--yes]

datasources

arkveil datasources create --name <n> --dialect POSTGRES|MYSQL|MARIADB|H2 [--description <d>]
arkveil datasources update <datasourceNodeId> --dialect <dialect> [--description <d>]
arkveil datasources delete <datasourceNodeId> [--yes]

Names are lowercased server-side and immutable — renaming means delete and recreate. Mutations return the full datasources tree; create prints the new node id. Deletion is refused (400) while any dataset still references the datasource.

datasets

arkveil datasets create --datasource <nodeId> --db-schema <s> --table-name <t> \
  --pk-name <col> --pk-type UUID|LONG|STRING --title <title> \
  [--description <d>] [--data-schema <json|@file|->]

arkveil datasets update <datasetNodeId> --title <t> --pk-name <col> --pk-type <type> \
  [--description <d>] [--data-schema <json|@file|->]

arkveil datasets impact <datasetCode>

arkveil datasets delete <datasetNodeId> [--yes]

dbSchema and tableName are lowercased and immutable — together they form the canonical dataset code datasource.schema.table, used by DATA targets, arkveil abac read/write, and dataset tests. Neither may be a Formula DSL keyword (data, user, where, ...).

update without --data-schema keeps the current schema; pass '{}' to clear it. Changing the data schema or primary key re-parses every policy that reads the dataset, and fails atomically, listing the affected policy ids if any break.

datasets impact <code> lists what blocks deletion (DATA targets and referencing policies), in the order they must be removed.

apply

Declarative manifest for datasources/datasets:

arkveil apply --file @data.json [--dry-run] [--prune] [--yes]
cat data.json | arkveil apply --file -

Diffs the manifest against the current datasources tree and executes only the needed creates/updates/deletes, in dependency order.

  • Identity (name, dbSchema/tableName) is immutable and compared case-insensitively.
  • dataSchema is always applied in full — omitting it means an empty schema.
  • Datasource descriptions omitted from the manifest are left unchanged.
  • --prune only deletes datasets under datasources declared in the manifest.
  • --dry-run prints the plan (add --json for a machine-readable plan).
  • Applying the same manifest twice is a no-op (idempotent).

actions

arkveil actions create --parent <id> --service <svc> --name <n> --title <t> \
  [--tag <slug> ...] [--description <d>] [--request-schema <json|@file|->]

arkveil actions update <actionNodeId> --title <t> [--tag <slug> ...] [--description <d>] [--request-schema <...>]

arkveil actions delete <actionNodeId> [--yes]

targets

arkveil targets create --parent <id> --type ACTION|DATA --mode INDIVIDUAL|CUSTOM|ALL \
  --title <t> [--action-code <code>] [--dataset-code <code>] [--condition <dsl>] [--request-schema <json|@file|->]

arkveil targets update <targetNodeId> --title <t> [--condition <dsl>] [--request-schema <...>]

arkveil targets delete <targetNodeId> [--yes]

arkveil targets suggest --condition '<dsl>'

A DATA target binds a dataset by its canonical code (the server lowercases it). targets suggest proposes a request schema derived from a condition.

policies

Policies attach to a target:

arkveil policies create <targetNodeId> --type PERMISSION|READ|WRITE|INVARIANT|PROJECTION \
  --status ENABLED|DISABLED|DRAFT|DELETED --title <t> \
  [--condition <dsl>] [--filter <dsl>] [--projection <json|@file|->]

arkveil policies update <targetNodeId> <policyId> --status <s> --title <t> [...]

arkveil policies delete <targetNodeId> <policyId> [--yes]

Dataset columns are referenced as data.<column> (the older entity. namespace has been removed with no compatibility shim — the CLI warns if it's used).

PERMISSION conditions can reference dataset rows via exists <dataset> where ...; the dataset must already exist. Prefer the canonical lowercase dataset code over a short/bare table name, which is resolved against live datasets at save time.

arkveil policies create <targetNodeId> --type PERMISSION --status ENABLED \
  --title "Invoice owner approval" \
  --condition 'exists demo_billing.public.invoice where data.id = request.invoiceId and data.owner_id = user.id'

tests

Access tests validate policies against fixtures.

# Permission-style test
arkveil tests create --parent <id> --name <n> --status DRAFT \
  [--selector-type ACTION_SET|FORMULA|ALL_ACTIONS] --expected-access GRANTED|DENIED \
  [--action-code <code> ...] [--formula <dsl>] \
  [--user '<json>'] [--context '<json>'] [--request '<json>'] [--tag <slug> ...] \
  [--must-be-granted-by <policyId> ...]

# Dataset test
arkveil tests create --parent <id> --name <n> --status ENABLED \
  --type DATASET_READ|DATASET_WRITE --dataset-code <datasource.schema.table> \
  [--user '<json>'] [--context '<json>'] --fixtures '<rows json>' [--expected-pk <pk> ...]

# From a full spec file
arkveil tests create --parent <id> --name <n> --status ENABLED --spec @spec.json

arkveil tests update <testNodeId> --name <n> --status <s> [...]
arkveil tests set-status <testNodeId> --status ENABLED
arkveil tests delete <testNodeId> [--yes]

arkveil tests run <testId>       # takes the test RESOURCE id, not the node id
arkveil tests run-all
arkveil tests history [testId]   # per-test or aggregate history
arkveil tests run-info <runId>   # a single run, with per-subject results

--type selects a single polymorphic specification — flags belonging to the other kind are rejected.

Dataset test example:

arkveil tests create --parent <folderId> --name "Regional user sees own region" \
  --status ENABLED --type DATASET_READ \
  --dataset-code demo_billing.public.invoice \
  --user '{"region":"EU"}' \
  --fixtures '[{"id":"1","region":"EU"},{"id":"2","region":"US"}]' \
  --expected-pk 1

--fixtures accepts either a row array or a full {"<dataset-code>": [rows]} map — [] means a legitimately empty table, not an omission. --expected-pk values are canonicalized locally (UUIDs lowercased, LONGs normalized). Dataset scenarios don't take --request.

Test name must be unique per workspace — there's no upsert; creating a duplicate returns 400.

settings

arkveil settings get
arkveil settings set [--theme LIGHT|DARK|SYSTEM] [--ui-mode SIMPLE|STRUCTURED]

schemas

Attribute JSON Schemas that drive typed SDK codegen:

arkveil schemas get <user|context|action>
arkveil schemas set <user|context|action> --data @schema.json

sdk

SDK install/usage info, useful for both humans and AI agents:

arkveil sdk info                       # all targets
arkveil sdk info <nest|node|core>
arkveil sdk info --json                # machine-readable catalog
arkveil sdk install <nest|node|core>   # print just the install command

--json returns, per package, the install command, a usage snippet, and the typing recipe — see the SDK docs.

generate

Generate a typed TypeScript SDK augmentation file for arkveil-js:

arkveil generate typescript -o src/arkveil.generated.ts
arkveil gen ts > src/arkveil.generated.ts       # alias; or pipe stdout
arkveil generate typescript --include user,context
arkveil generate typescript --json
OptionDescription
--include <items>Subset of codes,user,context to generate (default: all).
-o, --output <file>Write to a file instead of stdout.

Action codes are fetched from your workspace's action tree; user/context types are fetched from the attribute schemas configured via arkveil schemas set. Requires authentication. If no action codes are found, the generated union falls back to string and the command prints a warning. Without --output, the generated TypeScript is written to stdout and status messages go to stderr, so the output stays pipeable.

formula

The Formula DSL used by policy conditions and filters:

arkveil formula parse --context ACTION_PERMISSION --dsl 'user.role == "admin"'
arkveil formula syntax

eval

Explain an access decision:

arkveil eval explain -a orders:read --user '{"role":"admin"}' [--context '<json>'] [--request '<json>']

abac

CLI-equivalents of the SDK's decision operations:

arkveil abac check --action-code orders:read [--user '<json>'] [--context '<json>'] [--request '<json>']
arkveil abac read  --dataset-code <code> [--user '<json>'] [--context '<json>'] [--alias t]
arkveil abac write --dataset-code <code> [--user '<json>'] [--context '<json>'] [--id <rowId> ...]
arkveil abac action-data <service> <name>

Rules containing exists <dataset> where ... need a runtime that can see your data:

  • Against the Arkveil Cloud base URL, such a rule cannot be decided — the answer is granted: false, fail-safe rather than an error.
  • Point --base-url at a self-hosted sidecar with the datasource registered for a row-accurate decision. reason: "DATASOURCE_UNRESOLVED" there means the sidecar's arkveil.runtime.datasources.<name>.* config is missing or hasn't replicated yet.
  • Pure permission rules with no dataset references answer identically against either.

admin

Workspace administration/demo data:

arkveil admin seed-demo            # idempotent; preserves existing entities
arkveil admin reset-demo [--yes]   # destructive: wipes all authz data, then reseeds

seed-demo creates 8 tests (2 of them dataset tests over demo_billing.public.invoice) — running arkveil tests run-all afterward should report 8 passed.

update

arkveil update

Self-updates the CLI.

Configuration

Config file, environment variables, exit codes, and networking behavior for the Arkveil CLI.

On this page

healthtagstreesfoldersdatasourcesdatasetsapplyactionstargetspoliciestestssettingsschemassdkgenerateformulaevalabacadminupdate