API CLI
List, describe, and call Signals v1 API endpoints in-process with php artisan signals:api — auth, flags, plugin tools, scripting, and LLM instructions.
Overview
php artisan signals:api is an Artisan surface for discovering and invoking the same /api/v1 catalogue the MCP server uses. Calls run in-process through OperationInvoker (full HTTP kernel, Sanctum abilities, metering, idempotency) — not via an outbound HTTP client.
Enable
- Open Admin → Users & Security → MCP & CLI.
- Enable API CLI (
api_cli.enabled). - For
call, the acting user (token owner or--user) must holdcli.access. - Mint a PAT on API Tokens when using
--token, scoped to the abilities you need. - When using
--user, approve a named CLI connection with only the required abilities.
list and describe require only that the CLI is enabled. call requires either --token, or both --user and --connection, plus cli.access.
Authentication
| Flag | Behaviour |
|---|---|
--token= |
Plain-text Sanctum personal access token. Abilities on that token apply to the API call. Token owner must hold cli.access. |
--user= + --connection= |
User id or email plus an active named CLI connection grant. The stored abilities apply to the call. No wildcard token is created. User must hold cli.access. |
Provide either --token, or --user with --connection, for call. Owners pass the application permission check via Gate::before, but the connection still needs explicit API abilities.
A named connection keeps one idempotency owner across grant rotations. A
rotation, revocation, permission change, or warehouse-scope change invalidates
replay authorization. Signals returns a 403 contract error instead of the
stored response, and it does not execute the original effect again.
Approve and inspect local grants:
php artisan signals:connection-grant approve \
[email protected] --kind=cli --connection=ops \
--ability=catalogue-items:read --ability=rentals:read
php artisan signals:connection-grant list [email protected] --kind=cli
php artisan signals:connection-grant revoke --grant-id=42
Command reference
php artisan signals:api
{action : list, describe, or call}
{endpoint? : Route name (e.g. api.v1.catalogue_items.index) or plugin tool name}
{--resource= : Filter list by catalogue resource}
{--method= : Filter list by HTTP method}
{--search= : Filter list by substring (route, resource, summary, uri)}
{--plugins : List plugin MCP/CLI tools instead of catalogue endpoints}
{--format= : Output format (list: table|json; describe: text|json; call: json|table)}
{--param=* : Path parameter as key=value (repeatable)}
{--query=* : Query parameter as key=value (repeatable, incl. filter[field][operator])}
{--data= : JSON body string, or @path/to/file.json}
{--idempotency-key= : Idempotency-Key header value}
{--token= : Plain-text Sanctum personal access token}
{--user= : Acting user id or email (requires a named CLI connection grant)}
{--connection= : Named CLI connection grant used with --user}
list
List catalogue endpoints (or plugin tools with --plugins).
| Flag | Notes |
|---|---|
--resource= |
Exact catalogue resource segment (case-insensitive), e.g. catalogue_items |
--method= |
HTTP method filter, e.g. GET |
--search= |
Substring across route name, resource, summary, URI |
--plugins |
List plugin tools exposed on the cli surface instead of API routes |
--format= |
table (default) or json |
Examples:
php artisan signals:api list
php artisan signals:api list --resource=catalogue_items --method=GET
php artisan signals:api list --search=rental --format=json
php artisan signals:api list --plugins
php artisan signals:api list --plugins --format=json
describe
Requires {endpoint} route name. Formats: text (default) or json.
php artisan signals:api describe api.v1.catalogue_items.index
php artisan signals:api describe api.v1.rentals.store --format=json
Text output includes method/URI, summary, ability, parameters, request body schema, response statuses, and SchemaRegistry filterable/sortable/searchable fields when available.
call
Invoke a catalogue endpoint or a plugin tool.
Catalogue endpoint
php artisan signals:api call api.v1.catalogue_items.index \
--token="$SIGNALS_PAT" \
--query="per_page=5" \
--query="filter[name][contains]=widget"
php artisan signals:api call api.v1.catalogue_items.show \
[email protected] \
--connection=ops \
--param="catalogue_item=42"
php artisan signals:api call api.v1.catalogue_items.store \
--token="$SIGNALS_PAT" \
--data='{"name":"Widget","catalogue_item_type":"rental"}' \
--idempotency-key="$(uuidgen)"
php artisan signals:api call api.v1.catalogue_items.store \
--token="$SIGNALS_PAT" \
--data=@./payload.json \
--idempotency-key=job-123
| Flag | Notes |
|---|---|
--param=* |
Path params as key=value (repeatable) |
--query=* |
Query params as key=value (repeatable; supports filter[field][operator]) |
--data= |
JSON object string, or @path/to/file.json |
--idempotency-key= |
Sent as Idempotency-Key |
--format= |
json (default) or table (flat collections only; otherwise falls back to JSON with a warning) |
Exit code: 0 on HTTP 2xx, 1 on failure (unknown endpoint, auth denial, non-2xx, invalid flags).
Plugin tool
Namespaced name: plugin:{package}:{tool} (package may contain /).
php artisan signals:api list --plugins
# Requires the separately installed signals/slots-demo example plugin.
php artisan signals:api call plugin:signals/slots-demo:signals.slotsdemo.echo \
--user=1 \
--connection=ops \
--data='{"message":"hello"}'
Plugin call uses --data as the tool argument object (not HTTP body semantics). The acting user must pass cli.access and the tool's declared permission. Tools must expose the cli surface.
Output formats
| Action | Default | Allowed |
|---|---|---|
list |
table |
table, json |
describe |
text |
text, json |
call |
json |
json, table |
Invalid --format prints an error and exits non-zero.
Scripting examples
# JSON pipeline: first catalogue item ID
php artisan signals:api call api.v1.catalogue_items.index \
--token="$SIGNALS_PAT" --query="per_page=1" --format=json \
| jq '.data[0].id'
# Discover then describe
php artisan signals:api list --search=accounts --format=json \
| jq -r '.[].route_name' \
| head -1 \
| xargs -I{} php artisan signals:api describe {} --format=json
# Fail a script on API errors
set -e
php artisan signals:api call api.v1.catalogue_items.show \
--token="$SIGNALS_PAT" --param="catalogue_item=999999" \
|| echo "call failed with exit $?"
Aggregation (reporting reads)
GET /api/v1/aggregate/{model} — group-by + measure over a SchemaModelCatalog model, without paging the whole collection client-side.
# Revenue by month (money measures are summed in minor units)
php artisan signals:api call api.v1.aggregate.show \
--token="$SIGNALS_PAT" \
--param="model=rentals" \
--query="group_by=starts_at" --query="bucket=month" \
--query="measure=subtotal" --query="fn=sum"
# Outstanding by account, filtered to issued invoices
php artisan signals:api call api.v1.aggregate.show \
--token="$SIGNALS_PAT" \
--param="model=invoices" \
--query="group_by=account_id" --query="measure=amount_outstanding" --query="fn=sum" \
--query="filter[status][eq]=issued"
Bulk writes
POST {resource}/bulk accepts a {resource} array of row payloads (same shape as the single-row create endpoint) and returns per-row results — HTTP 201 when every row succeeds, 207 (Multi-Status) when some rows fail so the caller can retry only the failed indices.
php artisan signals:api call api.v1.activities.bulk \
--token="$SIGNALS_PAT" \
--data='{"activities":[{"title":"Call A"},{"title":"Call B"}]}'
php artisan signals:api call api.v1.accounts.bulk \
--token="$SIGNALS_PAT" \
--data=@./accounts-batch.json \
--idempotency-key="$(uuidgen)"
Dry-run (preview before mutating)
Rental transition endpoints (transitions with a to target, or change_status) accept dry_run=true (query or body) to run the guard pipeline and return a verdict in data, containing dry_run, allowed, reason, and code, without applying the transition — useful for an agent that wants to check feasibility before spending a mutating call.
php artisan signals:api call api.v1.rentals.change_status \
--token="$SIGNALS_PAT" \
--param="rental=42" \
--data='{"status":"quote_held","dry_run":true}'
Associated-rental workflow
Read the tree first, attach an existing child or create a copied extension, then complete only the descendants explicitly selected by the operator:
php artisan signals:api call api.v1.rentals.tree \
--token="$SIGNALS_PAT" \
--param="rental=42"
php artisan signals:api call api.v1.rentals.associations.store \
--token="$SIGNALS_PAT" \
--param="rental=84" \
--data='{"parent_rental_id":42}' \
--idempotency-key=associate-84-to-42
php artisan signals:api call api.v1.rentals.extend \
--token="$SIGNALS_PAT" \
--param="rental=42" \
--data='{"title":"Festival load-out extension","starts_at":"2026-09-08T08:00:00Z","ends_at":"2026-09-09T18:00:00Z"}' \
--idempotency-key=extend-rental-42-load-out
php artisan signals:api call api.v1.rentals.cascade_preview \
--token="$SIGNALS_PAT" \
--param="rental=42" \
--query="action=complete"
php artisan signals:api call api.v1.rentals.complete \
--token="$SIGNALS_PAT" \
--param="rental=42" \
--data='{"cascade_rental_ids":[84,91],"cascade_expected_versions":{"84":5,"91":2},"expected_version":17}' \
--idempotency-key=complete-rental-tree-42-v17
These calls require the normal rental permission plus rentals:read for the tree and rentals:write for association, extension, preview, and completion. cascade_rental_ids is an allow-list, not a recursive switch: omitted descendants remain unchanged. For a nonempty selection, copy the root's root_aggregate_version into expected_version and each selected child's aggregate_version into cascade_expected_versions. A missing or stale version refuses the whole cascade.
Project costs and crew assignments
Create a direct project cost through the nested project endpoint. For a project-owned person/account or dispatch-group crew assignment, service_id is required and identifies the Labour service whose company-base rate is snapshotted into the linked project cost.
php artisan signals:api call api.v1.rental_projects.costs.store \
--token="$SIGNALS_PAT" \
--param="rental_project=12" \
--data='{"description":"Site power","amount":"450.00","quantity":"1","currency":"GBP"}' \
--idempotency-key=project-12-site-power
php artisan signals:api call api.v1.resource-assignments.store \
--token="$SIGNALS_PAT" \
--data='{"rental_project_id":12,"resource_type":"account","resource_id":71,"service_id":19,"starts_at":"2026-09-02T10:00:00Z","ends_at":"2026-09-02T18:00:00Z","notes":"Lighting technician"}' \
--idempotency-key=project-12-crew-71-20260902
The project must already contain a live rental so its warehouse union is defined. The cost call uses projects:write; the assignment call uses resource-assignments:write and creates the assignment and Labour cost atomically.
Branding and colour settings groups
Read the two typed settings groups independently with least-privilege abilities, or partially update one group:
php artisan signals:api call api.v1.settings.show \
--token="$SIGNALS_PAT" \
--param="group=branding"
php artisan signals:api call api.v1.settings.show \
--token="$SIGNALS_PAT" \
--param="group=colour"
php artisan signals:api call api.v1.settings.update \
--token="$SIGNALS_PAT" \
--param="group=branding" \
--data='{"settings":{"accent_colour":"#047857","secondary_colour":"#188eaa","tertiary_colour":"#c07c91"}}' \
--idempotency-key=branding-palette-20260829
Reads accept settings:read, or the narrower settings:read:branding / settings:read:colour. Updates require settings.manage and settings:write; keys omitted from settings are left unchanged.
Cursor pagination
List endpoints accept cursor=1 (start) in place of page for large sweeps — the response meta carries next_cursor/prev_cursor instead of total/page, avoiding the cost of an offset count on big tables.
php artisan signals:api call api.v1.activities.index \
--token="$SIGNALS_PAT" \
--query="cursor=1" --query="per_page=100" --query="sort=id"
| Exit code | Meaning |
|---|---|
0 |
Success (list/describe completed, or call returned 2xx) |
1 |
Settings disabled, unknown action/endpoint, auth/permission denial, invalid options, or non-2xx call |
LLM instructions
- Confirm
api_cli.enabledand that the acting principal hascli.accessbefore mutating. - Prefer
list --search=/--resource=to discover route names, thendescribebeforecall. - Use curated MCP tools when connected over MCP; use this CLI for shell/automation and CI.
- On writes, pass
--idempotency-keywhen the API orapi.require_idempotency_keyrequires it. - Scope PAT and named connection abilities to the job. Revoke local grants that are no longer used.
- Parse
--format=jsonwithjq; treat exit code1as failure. - Plugin tools:
list --plugins, thencall plugin:{package}:{tool}with--dataargs. - Reach for
api.v1.aggregate.showbefore paging a whole collection to sum a measure client-side (revenue by month, outstanding by account, etc.). - Prefer
{resource}/bulkover N sequential single-rowcalls when creating more than a handful of rows; check each row'sstatusin thedataarray — a207response means partial success, not failure. - Pass
dry_run=trueon rental transition endpoints (transitionswith atotarget, orchange_status) to checkdata.allowed,data.reason, anddata.codebefore spending a mutating call. - Use
--query="cursor=1"(then followmeta.next_cursor) instead ofpage=when sweeping a large collection.