smeldr-cli
Generated from cli v0.37.2 by generator 0c423a7. Not edited by hand.
smeldr-cli is the command line for a Smeldr server. It reads the server's URL from SMELDR_URL and a token from SMELDR_TOKEN, or from .smeldr-cli.env in the working directory, which smeldr-cli init writes. Getting started shows how to download it and run init.
This page is the CLI's own help: the overview, then each command's --help.
Overview
smeldr-cli v0.37.2: Smeldr operator CLI
Usage:
smeldr-cli init [--url URL] [--bootstrap-token TOKEN] bootstrap a new instance
smeldr-cli <type> <verb> [slug] [flags] content operations
smeldr-cli token <verb> [args] token management
smeldr-cli grant [revoke|list] [args] governance role grants (Admin role required)
smeldr-cli content-type <define|redefine|get> [args] runtime-defined content types
smeldr-cli webhook <verb> [args] webhook management
smeldr-cli media <upload|list|delete> [args] media library: upload, list, delete files
smeldr-cli oauth revoke <token> revoke an OAuth token (Admin role required)
smeldr-cli history <type> <slug> [--limit n] one item's history, newest first (D101)
smeldr-cli reachability <type> <id> [--kind k] what is reachable from one item in the relation graph
smeldr-cli relation <list|withdraw> [args] list relations, or end one on purpose
smeldr-cli preview <prefix> <slug> generate draft preview URL
smeldr-cli social <subcommand> [args] social post, credential, and platform management
smeldr-cli block <node|section|item> <verb> [args] block system: nodes + composition (T32)
smeldr-cli nav <verb> [args] navigation tree management (Editor role required)
smeldr-cli redirect <verb> [args] redirect rule management (Editor role required)
smeldr-cli audit <subcommand> [args] audit trail (Editor role required)
smeldr-cli transition <type> <slug> --to <state> [--reason <text>] move an item via its registered StateFlow
smeldr-cli standing <type> <slug> [--json] show whether an item holds (D100)
smeldr-cli search [<text>] [--type t] [--state s] [--place p|none] find records across every type you may read
smeldr-cli decisions-for-paths --repo owner/name [--stdin] [<path>...] which Decisions apply to these files
smeldr-cli approvers <place> [--json] who approves an Organization, Domain or Area
smeldr-cli administrators [--json] who administers this instance
smeldr-cli findings [--detector D] [--type T] [--limit N] [--json] what the detectors found
smeldr-cli rests <type> <item> | --stored <type>:<item>... what rests on an item, and what it rests on (D150)
smeldr-cli premise confirm <decision> <premise> --reason "why" a Decision still holds although its premise is not in force (D149)
smeldr-cli coverage check --repo owner/name --stdin count what each coverage rule matches (Editor)
smeldr-cli decision sources <decision> [--set f.json|--clear] a Decision's pinned sources (D148)
smeldr-cli check change|merge|answer|show|list ... the pull request check (core T918)
smeldr-cli migrate-addresses [--apply] [--report <path>] give records their addresses (D110; dry run unless --apply; Admin)
smeldr-cli subscription <list|get|create|update|pause|resume|delete> [args] your event subscriptions (D116)
smeldr-cli signal <answer|withdraw> <address> [flags] answer or withdraw an open request (D115)
smeldr-cli watch [--subscription <address> | --channel <names>] [--after <id>] print the event stream
smeldr-cli logs [--level LEVEL] [--limit N] [--since RFC3339] [--json] live error log (Admin role required)
smeldr-cli status connectivity check
Content verbs (type is the URL path segment, e.g. "posts", "doc-pages"):
create --from <file> create a new draft
update <slug> --from <file> update fields (preserves absent fields)
publish <slug> transition to published
unpublish <slug> revert published item to draft
archive <slug> transition to archived
delete <slug> permanently delete
list [--status <s>] [--json] [--fields <a,b,c>] aligned table by default; --json for raw output
get <slug>
Token verbs (Admin role required):
create <name> <role> <ttl-days> issue a new named token
list list all tokens
revoke <id> revoke a token by fingerprint ID
Webhook verbs (Admin role required):
create --url <URL> --events <e1,e2,...> register a new endpoint
list list endpoints with delivery stats
delete <id> permanently remove an endpoint
deliveries --job <job-id> show delivery logs for a job
deliveries --endpoint <endpoint-id> show all jobs for an endpoint
retry <job-id> re-queue a dead-lettered job
Preview (Admin role required):
preview <prefix> <slug> generate signed draft preview URL (12 h)
Media subcommands:
upload <file> [--description <text>] upload a file to the media library
list [--type image|document|video|other] list media records
delete <id> permanently delete a media record
Social subcommands:
post create --credential <id> --body "..." [--platform mastodon|linkedin|x] [--at <RFC3339>]
post list [--status draft|scheduled|queued|published|archived|failed] [--json] [--fields <a,b,c>]
post get|publish|archive|delete <id>
credential create --platform mastodon|linkedin|x [--instance-url <url>]
credential list
credential get <id>
credential delete <id>
platform configure --platform mastodon|linkedin|x --client-id <id> --client-secret <secret> --redirect-url <url> [--instance-url <url>] [--success-url <url>]
Block subcommands (T32: Fields keys are case-sensitive PascalCase):
node create --type <type_name> [--field K=V ...] [--fields <json>] (Author)
node update <id> [--field K=V ...] [--fields <json>] (Author)
node get|publish|archive <id> (Author)
node list [--type <type_name>] [--status <s>] [--json] (Author)
section add|remove <parent_id> <child_id> (Editor)
section reorder <parent_id> <child_id1,child_id2,...> (Editor)
item add|remove <parent_id> <child_id> (Editor)
item reorder <parent_id> <child_id1,child_id2,...> (Editor)
Audit subcommands (Editor role required):
list [--from RFC3339] [--to RFC3339] [--type TYPE] [--actor ACTOR]
Transition (role required by the target StateFlow's own gate):
transition <type_name> <slug> --to <state> [--reason <text>]
type_name is dynamic (snake_case, e.g. "posts") or compiled (e.g.
"Decision", "Task", "Signal"). Example: ratifying a Decision:
smeldr-cli transition Decision <slug> --to ratified
Standing (Editor role required; needs smeldr.dev/mcp v1.46.0+ on the server):
standing <type_name> <slug> [--json]
prints holds, ceased or none, or "no standing for this type".
"<type> get/list" read the REST routes and do not show standing.
Search (Author role required; needs smeldr.dev/mcp v1.65.0+ on the server):
search [<text>] [--type t]... [--state s]... [--place p|none] [--limit n] [--offset n] [--json]
plain text, case-insensitive, across every type you may read; hidden records
never appear or count. --place none lists records without a place.
Coverage (needs smeldr.dev/mcp with core's coverage rules on the server):
decisions-for-paths --repo owner/name [--stdin] [--no-organization] [--json] [<path>...] (Author)
approvers <place> [--json] who approves a place you can read (Author; core T911)
administrators [--json] who administers this instance (any token; core T944)
findings [--detector D] ... what the detectors found, filtered by your reads (core T953)
rests <type> <item> [--json] live rest counts (core T919); --stored <type>:<item>... the swept ones
premise confirm <decision> <premise> --reason "why" (ratify over the Decision's place; core D149)
coverage check --repo owner/name [--stdin] [--json] [<path>...] (Editor)
paths as arguments or one per line with --stdin, for example from git diff --name-only.
History (Editor role required; needs smeldr.dev/mcp v1.49.0+ on the server):
history <type_name> <slug> [--limit n] [--offset n] [--view members|gated]
prints one item's history, newest first, as JSON; the actor is on every
entry for members (D101), only on gated transitions with --view gated.
Reachability (Author role required; needs smeldr.dev/mcp v1.50.0+ on the server):
reachability <type_name> <id> [--kind k] [--direction incoming|outgoing|both]
[--depth n] [--max-items n] [--limit n] [--offset n]
prints what is reachable from one item (live edges only, up to 10 hops) as
JSON; the walk is capped by --max-items and a cut is reported, not hidden.
Relation (Author role required; needs smeldr.dev/mcp v1.51.0+ on the server, list v1.58.0+):
relation list [--kind k] [--source-type t] [--target-type t] [--include-ended]
[--as-of RFC3339] [--limit n] [--offset n] [--all] [--json]
pages through every relation on the instance; --all pages to the total at
the first page's as_of. Prints a table, or JSON with --json.
relation withdraw <id> --reason <text>
ends a live relation on purpose; its row stays as history with you and the
reason on record. An ended relation is refused. Relations are never deleted.
OAuth subcommands:
revoke <token> revoke an OAuth refresh token (RFC 7009)
Environment variables:
SMELDR_URL base URL of the running Smeldr instance (required)
SMELDR_TOKEN bearer token with appropriate role (required)
SMELDR_MCP_URL MCP message endpoint (default: SMELDR_URL/mcp/message)
Configuration can also be stored in .smeldr-cli.env in the working directory.init
Usage: SMELDR_BOOTSTRAP_TOKEN=... smeldr-cli init [--url URL] [--name NAME] [--days N] [--force] [--no-approver]
or: smeldr-cli init --bootstrap-token-stdin [...] < token.txt
Creates your token (class human, admin and approver: it can ratify Decisions) and writes .smeldr-cli.env.
-bootstrap-token string
the bootstrap token from the startup log (deprecated: use $SMELDR_BOOTSTRAP_TOKEN or --bootstrap-token-stdin)
-bootstrap-token-stdin
read the bootstrap token from the startup log from the first line of stdin
-days int
Token TTL in days (default 365)
-force
Overwrite existing .smeldr-cli.env
-name string
Name for the created admin token (default "operator")
-no-approver
grant admin only: the token cannot ratify Decisions
-url string
Base URL of the Smeldr instance (default "http://localhost:8080")token
smeldr-cli token: token management (Admin role required)
Verbs:
create <name> <role> <ttl-days> [--class agent|job|human] [--identity <IDN>] [--reason <text>]
issue a new named token; --class classifies its actor;
--identity mints it for that identity (it joins it, D165)
list list all tokens (incl. revoked/expired)
revoke <id> [--reason <text>] revoke a token by fingerprint ID
--reason is stored with the act and shown by "token list". It is free text
that people read: never put a token value or other secret in it.
The MCP endpoint is used for token operations (SMELDR_MCP_URL).grant
smeldr-cli grant: governance role grants (Admin role required)
Usage:
grant <token-id> <role> [--scope type:id ...] [--anchor <id>] [--expires-in-days N] [--reason <text>] [--rev <n>]
grant a role to a token
grant revoke <grant-id> [--reason <text>] [--rev <n>]
revoke a grant by its own id
grant list [<token-id>] list all grants, or one token's
<token-id> is the token's JWT user id (token_id from "token create"), not the
fingerprint "token list" shows. --scope may repeat (static scope patterns,
"type:id" or "type:*"); --anchor is the anchor item id for a dynamic scope.
--expires-in-days makes the grant time-boxed (a positive number of days): when
it expires it stops authorizing, with no revoke needed, and "grant list" still
shows it.
--rev is the rev of the holder's identity you read (identity_rev in "grant list
<token-id>"): a grant or revoke on a stale view is refused. Without --rev, on a
terminal, cli shows the identity's grants and asks; without a terminal it
refuses. A holder that is not an identity yet names no rev.
--reason is stored with the act and shown by "grant list". It is free text that
people read: never put a token value or other secret in it.
The MCP endpoint is used (SMELDR_MCP_URL).content-type
smeldr-cli content-type: runtime-defined content types
Usage:
content-type define --type <name> --fields <file.json> [--url-prefix /p] [--label L]
define a new type (Admin, define-type)
content-type redefine --type <name> --fields <file.json> [--label L] [--reason R]
change an existing type's schema (Admin, define-type)
content-type get <name> print a type's schema (Author)
--fields is a JSON file holding the full field list: an array of
{name, type, required, format, role, description} objects.
A redefinition takes effect at once, for later writes. It may change the label,
a field's role, format and description, make a required field optional and add
optional fields. It refuses removing a field, changing its type, making it
required, a new required field, and any url_prefix change.
--reason is stored with the change. It is free text that people read: never put
a secret in it.
The MCP endpoint is used (SMELDR_MCP_URL).webhook
smeldr-cli webhook: outbound webhook management (Admin role required)
Verbs:
create --url <URL> --events <e1,e2,...> register a new endpoint
list list endpoints with delivery stats
delete <id> permanently remove an endpoint
deliveries --job <job-id> show delivery logs for a job
deliveries --endpoint <endpoint-id> show all jobs for an endpoint
retry <job-id> re-queue a dead-lettered job
Event names follow the pattern <type>.<lifecycle>, e.g.:
post.created post.updated post.published post.unpublished
post.scheduled post.archived post.deleted post.transitioned
<type>.updated is a content edit; <type>.transitioned fires once for every
status change, with from_state, to_state, reason and the actor (needs a core
release with D107 on the server).
The MCP endpoint is used for webhook operations (SMELDR_MCP_URL).media
smeldr-cli media: file upload, listing, and deletion
Usage:
smeldr-cli media upload <file> [--description <text>]
smeldr-cli media list [--type image|document|video|audio|other]
smeldr-cli media delete <id>
Subcommands:
upload Upload a file to the Smeldr media library.
--description / -d is required for image files (WCAG 1.1.1).
Prints the URL of the uploaded file on success.
list List all media records. Optional --type / -t filter.
Prints a table of ID, Type, Uploaded, Original, URL.
delete Permanently delete a media record by ID.
Environment:
SMELDR_URL base URL of the running Smeldr instance (required)
SMELDR_TOKEN bearer token with Editor or Admin role (required)oauth
smeldr-cli oauth: OAuth tokens issued by smeldr.dev/oauth
Usage:
smeldr-cli oauth revoke <token> revoke one OAuth access or refresh token
Needs SMELDR_URL and an Admin token in SMELDR_TOKEN, and a server with OAUTH_ISSUER set.history
smeldr-cli history: show one item's history, newest first (D101)
Usage:
smeldr-cli history <type_name> <slug> [--limit n] [--offset n] [--view members|gated]
Prints the tool's result as JSON: every recorded change with its time (UTC,
second resolution), verb (create, update, transition, standing-began,
standing-ended), from and to state, and whether the act was gated. By default
(--view members) every entry carries its actor: actor_kind (job, agent, human
or unclassified), actor_id, surface and reason. --view gated narrows the answer
to the rule for a wider audience: the actor appears only on a gated transition.
You can only narrow your view, never widen it. Rows written before core v1.121.0
say human for an actor with no classification and mean unclassified, never a
verified person. --limit defaults to 50 (at most 500); total is the whole
history. Relation events are not part of this read. type_name is dynamic
(snake_case) or compiled (e.g. "Decision", "Task").
Requires Editor role. Needs smeldr.dev/mcp v1.49.0 or later on the server, with
provenance enabled (an error says so when it is not).reachability
smeldr-cli reachability: what is reachable from one item in the relation graph
Usage:
smeldr-cli reachability <type_name> <id> [--kind k] [--direction incoming|outgoing|both]
[--depth n] [--max-items n] [--limit n] [--offset n]
Prints the tool's result as JSON: the items found at each hop distance (up to
10), each with its depth, type, id and the edge_class and confidence of the edge
that reached it. Live edges only: a relation that has ended is not walked.
direction is the walk's own vocabulary (incoming, outgoing, both; default both),
not the source and target of relation queries. The walk is bounded: --max-items
(default 500, at most 2000) caps how many items it returns. When the cap stops
the walk, "cut" says where: {depth, dropped} means the cap landed in ring depth
and dropped items found there were not returned; deeper rings were not walked
and are absent (never shown as empty). ring_sizes gives the count per returned
ring and total the number of items the walk returned; --limit (default 100, at
most 500) and --offset page the items. Graph structure only, no item content.
Requires Author role. Needs smeldr.dev/mcp v1.50.0 or later on the server.relation
smeldr-cli relation: list relations, or end one on purpose
Usage:
smeldr-cli relation list [--kind K] [--source-type T] [--target-type T]
[--include-ended] [--as-of RFC3339]
[--limit N] [--offset N] [--all] [--json]
smeldr-cli relation withdraw <id> --reason <text>
list pages through every relation on the instance (list_relations), ordered
by created_at then id. The first page fixes as_of; --all pages on with it to
the total, so one command prints the whole graph as it was at that moment.
Live edges only unless --include-ended. Source and target ids are the items'
raw ID, as the list tools return them. Requires Author role. Needs
smeldr.dev/mcp v1.58.0 or later on the server.
withdraw ends the live relation <id> (an edge id from get_relations or
relation list). Its row stays as history, ended now, and the end is recorded
with you as the actor and your reason (cause "withdrawn"). Asserting the same
relation again later starts a new row. A relation that has already ended is
refused. There is no delete for relations. Requires Author role (operation
archive). Needs smeldr.dev/mcp v1.51.0 or later on the server.preview
smeldr-cli preview: generate a signed draft preview URL (Admin role required)
Usage:
smeldr-cli preview <prefix> <slug>
Arguments:
prefix URL prefix of the content module (e.g. /posts, /docs). Must include the leading slash.
slug Slug of the draft item to preview (e.g. my-draft-post).
The preview URL bypasses Published-only visibility for the token lifetime (default 12 h).
The full URL is printed to stdout and can be shared with reviewers without a login.
Examples:
smeldr-cli preview /posts my-draft-post
smeldr-cli preview /docs getting-started-draft
The MCP endpoint is used for this operation (SMELDR_MCP_URL).social
smeldr-cli social: social management
Subcommands:
post <verb> [args] manage scheduled social posts
credential <verb> [args] manage platform OAuth credentials
schedule <verb> [args] manage publication schedules
platform <verb> [args] manage per-platform OAuth app configuration
Post verbs:
create --credential <id> --body "..." [--platform mastodon|linkedin|x] [--at <RFC3339>]
queue --credential <id> --body "..." [--platform mastodon|linkedin|x]
list [--status draft|scheduled|queued|published|archived|failed] [--json] [--fields <a,b,c>]
aligned table by default (columns: id, platform, status, scheduled_at)
get <id>
publish <id>
archive <id>
delete <id>
Credential verbs:
create --platform mastodon|linkedin|x [--instance-url <url>]
list
get <id>
delete <id>
Schedule verbs:
create --credential <id> --slot "<weekday> HH:MM IANA/TZ" [--slot ...]
show --credential <id>
pause --credential <id>
resume --credential <id>
delete --credential <id>
Platform verbs:
configure --platform mastodon|linkedin|x --client-id <id> --client-secret <secret> --redirect-url <url> [--instance-url <url>] [--success-url <url>]
Post commands use SMELDR_URL + bearer token (SMELDR_TOKEN).
Credential/schedule/platform commands use the MCP endpoint (SMELDR_MCP_URL).block
smeldr-cli block: block system (T32)
Subcommands:
node <verb> [args] manage blocks (generic content nodes)
section <verb> [args] compose page sections
item <verb> [args] compose collection items
Node verbs (Author role):
create --type <type_name> [--field K=V ...] [--fields <json>]
update <id> [--field K=V ...] [--fields <json>]
get <id>
list [--type <type_name>] [--status <s>] [--json]
publish <id>
archive <id>
Section / item verbs (Editor role):
add <parent_id> <child_id>
reorder <parent_id> <child_id1,child_id2,...>
remove <parent_id> <child_id>
Block Fields keys are CASE-SENSITIVE: use PascalCase (Title, Body, Headline)
to match block templates. Blocks are addressed by ID (no slug).
Operations are sent to the MCP endpoint (SMELDR_MCP_URL).nav
smeldr-cli nav: navigation tree management (Editor role required)
Verbs:
list list all navigation items
list --json list items as JSON
create --label <label> [flags] create a navigation item
update <id> [flags] update a navigation item
delete <id> delete an item and all its descendants
Flags for create / update:
--label <text> display label (required for create)
--path <path> URL path prefix, e.g. /learn
--parent-id <id> ID of parent item (top-level if omitted)
--module <name> module table name this item maps to
--hidden exclude from navigation, keep in breadcrumbs
--ghost non-clickable structural grouping node
--sort-order <n> display order within parent (lower = earlier)
Writes require the server to be in DB nav mode. list works in any nav mode.
The MCP endpoint is used for all nav operations (SMELDR_MCP_URL).redirect
smeldr-cli redirect: runtime redirect management (Editor role required)
Verbs:
list list all redirect rules
list --json list redirects as JSON
create --from <path> --to <path> create a 301 redirect
create --from <path> --to <path> --code 302 create a 302 redirect
create --from <path> --code 410 create a 410 Gone rule
create --from <path> --to <path> --prefix create a prefix redirect
delete <from-path> delete a redirect rule
The MCP endpoint is used for redirect operations (SMELDR_MCP_URL).audit
smeldr-cli audit: audit trail (Editor role required)
Verbs:
list [flags] show audit records, newest first
Flags for list:
--from <RFC3339> filter records at or after this timestamp
--to <RFC3339> filter records at or before this timestamp
--type <string> filter by content type (e.g. "Post")
--actor <string> filter by actor ID
The audit endpoint (GET /_audit) is called directly (not via MCP).transition
smeldr-cli transition: move an item to a new state via its registered StateFlow
Usage:
smeldr-cli transition <type_name> <slug> --to <state> [--reason <text>] [--rev <n>]
type_name is a registered content type name: dynamic (snake_case, e.g.
"posts") or compiled (e.g. "Decision", "Task", "Signal"). The transition is
validated against the type's registered flow; the target instance's own
role gate (RequiredRole/RequiredOperation) applies. --reason is required
only if the target transition itself requires one.
Example: ratifying a Decision:
smeldr-cli transition Decision <slug> --to ratified
--rev is the rev of the record you read; it is needed for these types: amendment, area, coverage_rule, decision, domain, organization.
Without --rev, on a terminal, cli shows the record and asks before it
writes; without a terminal it refuses.standing
smeldr-cli standing: show whether an item's claim is in force (D100)
Usage:
smeldr-cli standing <type_name> <slug> [--json]
Prints holds, ceased or none (an item of a type that has standing but no
stored row is none), or "no standing for this type" when the type has no
standing at all (in rare cases the server could not read the type's flow, which
is logged on the server, and the output is the same). type_name is dynamic (snake_case) or compiled (e.g.
"Decision", "Amendment"). --json prints the tool's whole result instead.
Requires Editor role. Needs smeldr.dev/mcp v1.46.0 or later on the server.
Note: "<type> get" and "<type> list" read the REST routes and do not show
standing; use this command or the MCP get tools for it.
Example:
smeldr-cli standing Decision <slug>search
smeldr-cli search: find records across every type you may read
Usage:
smeldr-cli search [<text>] [--type <t>]... [--state <s>]... [--place <p>|none]
[--limit n] [--offset n] [--json]
Matches plain text, case-insensitively, in each type's searchable fields
(title, body, description, summary, message and the like); 2 to 200
characters. Records you may not read never appear and never count. The text
may be left out when a filter is set. --place none lists records without a
place (no Domain or Area), for example imported Decisions in the inbox; a
Domain or Area by address, slug or ID lists the records placed there. Newest
first, 50 per page (at most 500). --json prints the tool's whole result.
Requires Author role. Needs smeldr.dev/mcp v1.65.0 or later on the server.
Examples:
smeldr-cli search "release plan"
smeldr-cli search --type Decision --state proposed --place nonedecisions-for-paths
smeldr-cli decisions-for-paths: which Decisions apply to these files
Usage:
smeldr-cli decisions-for-paths --repo owner/name [--stdin] [--no-organization] [--json] [<path>...]
Gives the Areas whose coverage rules match the paths, the Decisions in force
placed in those Areas, their Domains and on the Organization
(--no-organization leaves the last out), and the paths no rule covers. Paths
come as arguments or one per line with --stdin; at most 3000 per call.
Records you may not read never appear. Requires Author role. Needs
smeldr.dev/mcp with core's coverage rules (the places release) on the server.
Examples:
git diff --name-only main | smeldr-cli decisions-for-paths --repo acme/app --stdin
smeldr-cli decisions-for-paths --repo acme/app internal/billing/invoice.goapprovers
smeldr-cli approvers: who approves a place
Usage:
smeldr-cli approvers <place> [--json]
<place> is an Organization, Domain or Area by address, slug or ID (DOM4, ARE3).
Lists every approver, the domain-approvers of the place's Domain and, for an
Area, its area-approvers: token name, role, class and the anchor's address
("-" when you may not read it). Only for a place you can read. Author role;
needs smeldr.dev/mcp with approvers_of (core T911) on the server.administrators
smeldr-cli administrators: who administers this instance
Usage:
smeldr-cli administrators [--json]
Lists who administers the instance: token name and class (human, agent, job,
unclassified), nothing else. Ask one of them for a grant, a token or a change
to the instance's setup. Any authenticated token may ask, also one with no
grant yet; needs smeldr.dev/mcp with administrators (core T944) on the server.findings
smeldr-cli findings: what the detectors found
Usage:
smeldr-cli findings [--detector D] [--type T] [--limit N] [--json]
Lists recorded findings newest first: detector (structural, eval-queue,
standing-drift, ...), subject (its address, or type:id), when last seen, and
the message. You see a finding only when you may read its subject. Findings
resolve when their detector stops firing; nothing here dismisses one.
--limit is 1 to 500 (default 100). Needs smeldr.dev/mcp with list_findings
(core T953) on the server.rests
smeldr-cli rests: what rests on an item, and what it rests on (core T919)
Usage:
smeldr-cli rests <type> <item> [--json]
smeldr-cli rests --stored [--json] <type>:<item>...
The live form counts the items reached over grounded_in, addresses and amends,
transitively, each once, open and closed, only those you may read; "at least"
when the walk stopped at 1,000. --stored reads what the last sweep stored for
up to 200 items, summed over the places you read: it may be lower than the
live count, never higher. Items are named by address, slug or ID.premise
smeldr-cli premise: a Decision resting on one that is not in force (core D149)
Usage:
smeldr-cli premise confirm <condition> --reason "why"
smeldr-cli premise confirm <decision> <premise> --reason "why"
Resolves the premise-flagged condition: the Decision still holds. Name the
condition (its Signal address) when you may not read the premise.
It stays closed until the premise's state changes. Needs ratify over the
Decision's place; agents never confirm.coverage
smeldr-cli coverage check: count what each coverage rule matches
Usage:
smeldr-cli coverage check --repo owner/name [--stdin] [--json] [<path>...]
Give the repository's full file list (one per line with --stdin, at most
100000). Each coverage rule of the repository gets its match count stored; a
rule that matches nothing opens a coverage-matches-nothing condition, which
resolves when it matches again or is changed. Requires Editor role. Needs
smeldr.dev/mcp with core's coverage rules (the places release) on the server.
Example:
git ls-files | smeldr-cli coverage check --repo acme/app --stdindecision
smeldr-cli decision: Decisions
Usage:
smeldr-cli decision create --from <file> propose a Decision (title, scope, body from the file)
smeldr-cli decision update <slug> --from <file> update fields (absent fields preserved)
smeldr-cli decision get <slug> print one Decision as JSON
smeldr-cli decision list [--status <s>] [--json] list Decisions
smeldr-cli decision sources <decision> [--set f.json|--clear] [--rev N]
a Decision's pinned sources (D148)
A Decision starts proposed; ratifying it is smeldr-cli transition Decision <slug> --to ratified.
See smeldr-cli decision sources --help for the sources file format.check
smeldr-cli check: the pull request check (core T918)
Usage:
smeldr-cli check change --repo owner/name --number N --head SHA [--files-total N] [--stdin] [--json] [<path>...]
smeldr-cli check merge --repo owner/name --number N --head SHA --merge SHA [--json]
smeldr-cli check answer <check> <area> --approve | --not-approved --reason "why" [--json]
smeldr-cli check show <check> [--json]
smeldr-cli check list [--repo owner/name [--number N]] [--area A] [--decision D] [--status S] [--limit N] [--json]
Flags may come before or after the arguments; an unknown flag or a stray
argument is refused.
change and merge are for the host's adapter or an operator (check_change
capability). answer counts when you hold approve-change over that Area (or
item-change-approver on the Check). list needs a repository, an Area or a
Decision: Checks are read by filter.migrate-addresses
smeldr-cli migrate-addresses: give every record without an address its address (D110)
Usage:
smeldr-cli migrate-addresses [--apply] [--report <path>]
Without --apply this is a dry run: the server runs the whole migration in one
transaction and rolls it back, so the report shows exactly what an apply would
do and nothing is written. --apply writes it. A second apply changes nothing.
The report is printed to stdout as JSON: per type the prefix, counts before
and after, every renumbered record with its old and new address, every
rewritten reference and every reference left alone, and duration_ms, how long
the database writer was held. A one-line summary goes to stderr. --report also
writes the report to a file.
Applying is a governance act: run a dry run first, read the report, back up
the database, and keep the report with the deploy record (renumbered Decisions
are part of the governance record, and the instance stores no copy).
Requires the Admin role (the administer operation under governance) and
smeldr.dev/mcp v1.60.0 or later with smeldr.dev/core v1.145.0 or later on the
server.
Example:
smeldr-cli migrate-addresses --report dry.json
smeldr-cli migrate-addresses --apply --report apply.jsonsubscription
smeldr-cli subscription: your event subscriptions (D116, Author role)
Usage:
subscription list [--owner <user-id>] your subscriptions, the three defaults included
subscription get <address> one subscription (N12, slug or ID)
subscription create --name <label> [--filter <json>|@<file>] [--include-own] [--paused] [--owner <user-id>]
subscription update <address> [--name <label>] [--filter <json>|@<file>] [--include-own=true|false]
subscription pause <address>
subscription resume <address>
subscription delete <address> the defaults cannot be deleted; pause them
A subscription is what "smeldr-cli watch --subscription <address>" receives.
--filter is a JSON object: types, events, event_names, from_states, to_states,
items, related_to, fields, signal_kinds, addressed_to_me, sent_by_me; an
unknown key is refused. --owner names another token, which needs administer.
The MCP endpoint is used (SMELDR_MCP_URL). Needs smeldr.dev/mcp v1.64.0 or later.signal
smeldr-cli signal: answer or withdraw an open request (D115, Author role)
Usage:
signal answer <address> --text <answer> [--ref <Type:ident>]
signal withdraw <address> --reason <text>
--ref names the change the answer made, such as Task:T42.
The MCP endpoint is used (SMELDR_MCP_URL). Needs smeldr.dev/mcp v1.64.0 or later.watch
smeldr-cli watch: print the event stream, one JSON line per event (Author role)
Usage:
watch --subscription <address> [--after <event-id>]
watch --channel <name[,name...]> [--after <event-id>] [--include-own]
--subscription delivers one of your subscriptions ("smeldr-cli subscription
list"); without --after it resumes from the subscription's saved cursor.
--channel routes as before (D97). With neither, you get all your
subscriptions.
Each event is printed to stdout as it arrives, so the command works as a
monitor. Heartbeats are not printed; caught_up and skipped go to stderr. A
dropped or closed connection is reconnected with ?after=<last event id>, with
a backoff of 1 s doubling to 30 s, and an event seen twice is printed once.
401, 403 and 404 end the command with exit 1. Ctrl-C stops it.
Needs smeldr.dev/core v1.162.0 or later on the server for --subscription.logs
Usage: smeldr-cli logs [--level LEVEL] [--limit N] [--since RFC3339] [--json]
Requires Admin role. The server must call app.CaptureLogs() (core v1.36.0+).status
Usage: smeldr-cli status