dist.town

docs/CLI reference

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.

login

sh
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 (override; normally resolved from the identifier’s DID document)

storage

Configure and check your artifact storage (BYOS)

storage setup

sh
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> — shell command template with {file} and {key} placeholders (e.g. ‘aws s3 cp {file} s3://bkt/{key}‘)

storage doctor

sh
disttown storage doctor

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

publish

sh
disttown publish <version> <artifact files...> --project <project>

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

  • --project <value> — project name (required)
  • --channel <value> — release channel (e.g. stable, beta)
  • --license <value> — SPDX license identifier for this release
  • --pointer <value> — pointers to move to this release; 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)

pointer

Manage moving pointers (latest, next, …)

pointer set

sh
disttown pointer set <name> <version> --project <project>

Point a named pointer at a published version.

  • --project <value> — project name (required)

changelog

Author release notes as standard.site documents.

changelog set

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

Attach or update release notes for a published version.

  • --project <value> — project name (required)
  • --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
sh
disttown changelog link <version> --project <project> --doc <doc>

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

  • --project <value> — project name (required)
  • --doc <value> — the document to adopt: an rkey or at-uri in your own repo (required)
sh
disttown changelog unlink <version> --project <project> --doc <doc>

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

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

project

Manage project records.

project create

sh
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

sh
disttown project set <name>

Update a project’s optional fields (only the flags you pass change)

  • --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 rename

sh
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

sh
disttown publication set --project <project>

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 (required)
  • --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)

yank

sh
disttown yank <version> --project <project>

Mark a release do-not-newly-adopt (or undo with —undo); pins keep working.

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