CLI

idiolect is the command-line tool. The surface below reflects idiolect 0.13.0.

Top-level subcommands

idiolect resolve <did>
idiolect fetch <at-uri>
idiolect init --name NAME --did DID [--workspace DIR]
idiolect check|doctor [--workspace DIR]
idiolect propose|preview|review [...]
idiolect verify change <packet> [...]
idiolect keygen|release [...]
idiolect migrate <plan|advance|status> [...]
idiolect export --out DIR [...]
idiolect orchestrator <subcommand>
idiolect encounter record [...]
idiolect oauth login | list | logout [...]
idiolect publish <kind> --record <path> [...]
idiolect verify <kind> [...]
idiolect version          # also accepts --version, -V
idiolect help [<sub>]     # also accepts --help, -h

The hand-written subcommands (resolve, fetch, the community lifecycle, oauth, publish, verify, encounter) live in their own modules under crates/idiolect-cli/src/. The orchestrator subcommand is generated from orchestrator-spec/queries.json and routes its calls to the orchestrator's HTTP API.

`resolve`

idiolect resolve <did>

Resolve a DID via idiolect-identity::ReqwestIdentityResolver. Prints { did, method, handle, pds_url, also_known_as }.

`fetch`

idiolect fetch <at-uri>

Fetch a record body via com.atproto.repo.getRecord (under the hood: idiolect-lens::fetcher_for_did). Prints the record value as JSON.

`orchestrator <subcommand>`

The orchestrator dispatcher accepts a flat path-and-flags shape generated from orchestrator-spec/queries.json. Each query maps onto a subcommand and a flag set. The CLI translates the invocation into an HTTP path and calls the orchestrator at --url (default http://localhost:8787).

The current subcommands (run idiolect help orchestrator for the live list):

Command	Calls
`idiolect orchestrator adapters --framework <NAME>`	`GET /v1/adapters?framework=...`
`idiolect orchestrator bounties`	`GET /v1/bounties/open`
`idiolect orchestrator bounties --requester_did <DID>`	`GET /v1/bounties/by-requester?requester_did=...`
`idiolect orchestrator changes`	`GET /v1/changes/open`
`idiolect orchestrator changes --community_uri <AT-URI>`	`GET /v1/changes/for-community?community_uri=...`
`idiolect orchestrator releases --community_uri <AT-URI>`	`GET /v1/releases/for-community?community_uri=...`
`idiolect orchestrator migrations`	`GET /v1/migrations/active`
`idiolect orchestrator migrations --change_uri <AT-URI>`	`GET /v1/migrations/for-change?change_uri=...`
`idiolect orchestrator federations --community_uri <AT-URI>`	`GET /v1/federations/for-community?community_uri=...`
`idiolect orchestrator federations --peer_uri <AT-URI>`	`GET /v1/federations/for-peer?peer_uri=...`
`idiolect orchestrator recommendations`	`GET /v1/recommendations`
`idiolect orchestrator verifications --lens_uri <AT-URI>`	`GET /v1/verifications?lens_uri=...`

Adding a query to the spec extends both the HTTP and the CLI surface. See Run codegen. The CLI's top-level --url flag overrides the default orchestrator base.

Community lifecycle

The community commands operate on a local workspace and do not publish by themselves.

Command	Purpose
`init --name NAME --did DID`	Create `idiolect.toml`, a definition package, and managed artifact directories.
`check [--json]`	Validate manifest and package layout.
`doctor [--repair] [--json]`	Diagnose policy, paths, federation mappings, and artifact inventory; optionally recreate managed directories.
`propose --title … --old FILE --new FILE`	Produce a resource-bounded Panproto change packet.
`preview <packet> [--json]`	Print participant-facing consequences or the complete packet.
`review <packet> --reviewer DID --role ROLE --stance …`	Record or replace one attributable review and re-evaluate governance.
`verify change <packet> --kind KIND --outcome … --tool TOOL`	Attach `verified`, `refuted`, or `incomplete` evidence.
`keygen`	Create a P-256 community release key.
`release --version V --change PACKET --artifact FILE --key KEY --signer DID`	Gate, assemble, hash, sign, and write a community release.
`release verify <release.json>`	Verify bundle digest, ES256 signatures, authority membership, and threshold.
`migrate plan\|advance\|status`	Create and operate a durable migration run.
`export --out DIR [--release FILE]`	Write a portable, inventoried exit directory.

All accept --workspace DIR where a workspace is required; the default is the current directory. Repeat --change, --artifact, and --failure when a command accepts several values. See the new-community path for one complete runnable sequence.

`oauth`

Authenticated PDS sessions for idiolect publish and downstream record-writing flows.

idiolect oauth login  --handle HANDLE --app-password PASSWORD [--pds-url URL]
idiolect oauth list
idiolect oauth logout --did DID

login exchanges (handle, app-password) for an access JWT via com.atproto.server.createSession and persists {did, handle, pds_url, access_jwt, refresh_jwt} as one JSON file per DID under $IDIOLECT_SESSION_DIR (default ~/.config/idiolect/sessions/). --app-password may be passed as a flag or via ATPROTO_APP_PASSWORD / ATPROTO_PASSWORD env vars to avoid leaking into shell history.

list enumerates every stored session as a JSON array of {did, handle, pds_url} triples.

logout deletes the session file for --did. A missing file is not an error.

`publish <kind>`

idiolect publish <kind> --record <path> [--rkey RKEY] [--did DID]

Loads a JSON file, validates it against the typed Record impl for <kind> (which can be either the unqualified kind like recommendation or the fully-qualified NSID like dev.idiolect.recommendation), splices in a $type discriminator, and POSTs com.atproto.repo.createRecord using the stored session's bearer auth.

When --did is omitted, the CLI uses the first session returned by the filesystem scan; that order is unspecified. Pass --did in scripts and multi-account environments. When --rkey is omitted the CLI generates a TID-shaped key.

Prints {uri, cid} of the published record on success.

`verify <kind>`

idiolect verify roundtrip-test  --lens AT_URI [--corpus PATH]   [--pds-url URL] [--verifier-did DID]
idiolect verify property-test   --lens AT_URI  --corpus PATH    [--budget N]    [--pds-url URL] [--verifier-did DID]
idiolect verify static-check    --lens AT_URI                   [--pds-url URL] [--verifier-did DID]
idiolect verify coercion-law    --lens AT_URI  --vcs-url URL    --standard STD  [--version V] [--violation-threshold N] [--verifier-did DID]

Runs the shipped VerificationRunner for the given kind against the live PDS, prints the typed Verification record as JSON, and exits non-zero on Falsified / Inconclusive so CI surfaces failures.

The corpus file (for roundtrip-test and property-test) may be a JSON array or JSON Lines. property-test's generator cycles through the corpus by index, so --budget controls how many cases run.

`encounter record`

idiolect encounter record \
  --lens <AT-URI> --source-schema <AT-URI> [--target-schema <AT-URI>] \
  [--action-vocab <AT-URI>] [--kind <KIND>] [--visibility <V>] [--text-only]

Prints a dev.idiolect.encounter body after prompting for a structured use value. It does not publish the body. Save the JSON and pass it to idiolect publish encounter --record <path>.

Output format

Data commands print pretty-printed JSON to stdout. version and help print text. Errors go to stderr:

error: <message>

Pipe stdout to jq for further processing.

Authentication boundary

The shipped login path uses app passwords in legacy Bearer mode (com.atproto.server.createSession plus Authorization: Bearer <token>). Its session file is not an idiolect_oauth::OAuthSession and contains no DPoP private key. Applications that require OAuth with DPoP should use idiolect-oauth and an OAuth client directly.