CLI reference

All commands operate on your own repo via your logged-in session. Project names are accepted in both the URL form (dist-town/cli) and the record form (dist-town:cli). This page is generated from the CLI’s own command definitions.

init

disttown init

Write this repo’s disttown.jsonc — the committed facts publish infers from.

• --project <value> — project name (default: proposed from the directory name)
• --storage <value> — storage choice: a profile name, “blobs”, or empty to decide later
• --yes — accept the proposals without prompting

login

disttown login <handle-or-did>

Authenticate via OAuth in your browser (default) or an app password (—app-password)

• --app-password — prompt for an app password instead of the browser OAuth flow (the automation-style path)
• --broad — request the transitional blanket scope instead of granular town.dist.* scopes (for PDSes without granular scope support)
• --pds <value> — PDS base URL for —app-password logins (override; normally resolved from the identifier’s DID document, which is what the OAuth flow always does)

whoami

disttown whoami

Report the active identity, auth method, and whether the cached session’s scopes still suffice.

• --json — emit machine-readable JSON (additive-only compatibility surface)

logout

disttown logout

Clear the cached session and OAuth state on this machine (the server-side grant is not revoked)

update

disttown update

Update this binary from its publisher’s repo — no dist.town service involved; asks before replacing.

• --check — report only: exit 0 when current (or the target is yanked), 2 when an update is available
• --channel <value> — follow this channel’s pointer instead of latest
• --yes — consent without prompting (for automation)

doctor

disttown doctor [<project>]

Check publish-readiness: session, scopes, PDS, storage, and whether the index can see you.

storage

Configure and check your artifact storage (BYOS)

storage setup

disttown storage setup --base-url <base-url>

Record the bucket’s public base URL and optional upload command.

• --base-url <value> — public base URL artifacts are served from (required)
• --upload-cmd <value> — command template with {file} and {key} placeholders, run directly rather than through a shell (e.g. ‘aws s3 cp {file} s3://bkt/{key}’); for pipes or redirection, call a script
• --profile <value> — save as a named profile a repo manifest can pick (default: the machine-wide default bucket)

storage doctor

disttown storage doctor

Check the bucket against dist.town’s BYOS requirements.

• --profile <value> — check a named storage profile instead of the default bucket

publish

disttown publish [<version>] [<artifact files...>]

Publish a release: hash, upload, and write records atomically.

• --project <value> — project name (default: the governing manifest’s)
• --channel <value> — release channel (e.g. stable, beta); also redirects the default pointer to the channel name — latest moves only when named
• --license <value> — SPDX license identifier for this release
• --pointer <value> — pointers to move to this release; naming any replaces the default entirely (default: the channel name when —channel is set, else latest); repeatable
• --notes <value> — markdown file of release notes, published as a changelog document in the same commit
• --notes-title <value> — changelog document title (default: ”<project> <version>“)
• --no-pointers — do not move any pointers
• --blobs — store artifact bytes as blobs on your own PDS (no bucket needed; small artifacts only)
• --tag <value> — git tag this release was cut from: pins the source claim (annotated tags also enable Tangled artifact discovery)
• --git — pin the source claim to the local checkout’s HEAD commit (no tag)
• --attach-tangled — attach tag-matched Tangled artifacts without prompting (for CI)
• --dry-run — print the plan — digests, records, pointer moves — uploading nothing and writing nothing
• --yes — skip the interactive plan confirmation

release

Inspect releases and manage their lifecycle.

release list

disttown release list [<project>]

List releases: a named project’s, the manifest’s project inside a governed repo, or the whole repo’s.

• --pds — force the authoritative read from your own repo (a no-op for reads that already come from it, like pointer and project listings)
• --compare — read both your repo and the read plane and report where they disagree
• --json — emit machine-readable JSON (additive-only compatibility surface)

release show

disttown release show [<project>] <version-or-pointer>

Show one release in full: artifacts, digests, locations, pointers, source, changelog.

• --pds — force the authoritative read from your own repo (a no-op for reads that already come from it, like pointer and project listings)
• --compare — read both your repo and the read plane and report where they disagree
• --json — emit machine-readable JSON (additive-only compatibility surface)

release history

disttown release history [<project>] <version>

Print a release’s full lifecycle timeline — every statement, reasons intact, the governing one marked.

• --json — emit machine-readable JSON (additive-only compatibility surface)

release yank

disttown release yank [<project>] <version>

Mark a release do-not-newly-adopt; pins keep working.

• --kind <value> — machine-facing reason category (security, broken, superseded, …)
• --reason <value> — human-facing explanation
• --move <value> — pointer moves in the same commit, as name=version (e.g. latest=1.2.2); repeatable

release unyank

disttown release unyank [<project>] <version>

Restore a yanked release to active; the yank stays in history.

• --kind <value> — machine-facing reason category (security, broken, superseded, …)
• --reason <value> — human-facing explanation

release deprecate

disttown release deprecate [<project>] <version>

Mark a release still-works-stop-building-on-it; it keeps resolving, with a warning.

• --kind <value> — machine-facing reason category (security, broken, superseded, …)
• --reason <value> — human-facing explanation
• --move <value> — pointer moves in the same commit, as name=version (e.g. latest=1.2.2); repeatable

release undeprecate

disttown release undeprecate [<project>] <version>

Restore a deprecated release to active; the deprecation stays in history.

• --kind <value> — machine-facing reason category (security, broken, superseded, …)
• --reason <value> — human-facing explanation

release retract

disttown release retract [<project>] <version>

Last resort: delete a mistake-release, leaving testimony — yank is the norm for anything that ever had a consumer.

• --kind <value> — machine-facing reason category (broken, mistake, …)
• --reason <value> — human-facing explanation, preserved as the removal’s permanent testimony
• --yes — consent without prompting (for automation)

pointer

Manage moving pointers (latest, next, …)

pointer list

disttown pointer list [<project>]

List a project’s pointers and the versions they target.

• --pds — force the authoritative read from your own repo (a no-op for reads that already come from it, like pointer and project listings)
• --compare — read both your repo and the read plane and report where they disagree
• --json — emit machine-readable JSON (additive-only compatibility surface)

pointer remove

disttown pointer remove [<project>] <name>

Delete a pointer — a mutable alias nobody pins by identity; the name stops resolving.

• --yes — consent without prompting (for automation)

pointer set

disttown pointer set <name> <version>

Point a named pointer at a published version.

• --project <value> — project name (default: the governing manifest’s)

changelog

Author release notes as standard.site documents.

changelog set

disttown changelog set --file <file> <version>

Attach or update release notes for a published version.

• --project <value> — project name (default: the governing manifest’s)
• --file <value> — markdown file with the notes (plaintext fallback is derived) (required)
• --title <value> — document title (default: ”<project> <version>“)
• --site <value> — document site (default: the project’s publication, else its dist.town page)
• --tag <value> — subject tags, your vocabulary (the changelog type-tag is added automatically); repeatable
• --yes — skip the confirmation when editing a document that describes multiple releases

changelog link

disttown changelog link --doc <doc> <version>

Adopt an existing document as a release’s changelog — appends the release link, changes nothing else.

• --project <value> — project name (default: the governing manifest’s)
• --doc <value> — the document to adopt: an rkey or at-uri in your own repo (required)

changelog unlink

disttown changelog unlink --doc <doc> <version>

Detach a document from a release — removes the release link, changes nothing else.

• --project <value> — project name (default: the governing manifest’s)
• --doc <value> — the document to detach: an rkey or at-uri in your own repo (required)

project

Manage project records.

project list

disttown project list

List your projects, with alias and successor state.

• --pds — force the authoritative read from your own repo (a no-op for reads that already come from it, like pointer and project listings)
• --compare — read both your repo and the read plane and report where they disagree
• --json — emit machine-readable JSON (additive-only compatibility surface)

project create

disttown project create [<name>]

Create a bare project record (e.g. an umbrella; publish creates leaf projects on first release)

• --display-name <value> — human-facing name
• --description <value> — brief description

project set

disttown project set [<name>]

Update a project’s optional fields: only the flags you pass change, and passing an empty value clears that field.

• --display-name <value> — human-facing name
• --description <value> — brief description
• --source <value> — source repository: an at:// record uri (e.g. your sh.tangled.repo — same-DID sources are self-authenticated) or an https:// forge URL
• --website <value> — project homepage, distinct from source

project history

disttown project history [<name>]

Print a project’s full lifecycle timeline — every statement, reasons intact, the governing one marked.

• --json — emit machine-readable JSON (additive-only compatibility surface)

project archive

disttown project archive [<name>]

Mark a project archived; releases and pins keep working.

• --kind <value> — machine-facing reason category (security, broken, superseded, …)
• --reason <value> — human-facing explanation

project unarchive

disttown project unarchive [<name>]

Restore an archived project to active; the archival stays in history.

• --kind <value> — machine-facing reason category (security, broken, superseded, …)
• --reason <value> — human-facing explanation

project rename

disttown project rename <old-name> <new-name>

Rename a project: a successor record is created and the old record persists as a permanent alias.

publication

Manage the standard.site publication a project’s changelogs belong to.

publication set

disttown publication set

Create a publication anchored at a project, or link a project to an existing one.

• --project <value> — anchor project (created publications) or project to link (default: the governing manifest’s)
• --name <value> — publication name (required when creating)
• --description <value> — brief description
• --icon <value> — square image file, at least 256x256
• --url <value> — base publication url (default: the anchor project’s dist.town page)
• --publication <value> — at-uri of an existing same-DID publication to link instead of creating
• --link-only — only set the project’s publication field (requires —publication)