adompkg CLI Reference

npm-style package manager for Adom apps and skills. Every command, every flag, with examples.

Quick start

bash <(curl -fsSL https://git-wiki-ktqxite5iglh.adom.cloud/static/bootstrap.sh)

Installs adompkg + adom-core (the meta-package with the standard toolset) on any fresh container.

Primary

`install`

adompkg install [<owner>/<slug>[@version] ...] [--org <slug>] [--dev]

Install one or more packages from the registry. Packages are identified by
<owner>/<slug> (e.g. adom/core); a bare <slug> still works if it's globally
unique. With no arguments, reinstalls everything in .installed.json (handy for
migrating modules between machines).

Examples:
  adompkg install adom/core
  adompkg install adom/[email protected]
  adompkg install adom/mouser@^1.4.0
  adompkg install adom/mouser john/jlcpcb
  adompkg install mouser            # bare slug (resolves if unique)
  adompkg install                # reinstall everything in .installed.json
  adompkg install adom/mouser --dev   # also install root devDependencies

Flags:
  --org <slug>      install from a specific org's package namespace
  --dev, -D         also resolve the root packages' devDependencies. npm-shaped:
                    transitive devDeps of dependencies are NEVER walked, only the
                    direct devDependencies of the packages you ask for

Lifecycle hooks (defined in the installed package's package.json "scripts"):
  postinstall       runs inside the installed module directory after install.sh
                    succeeds. Use for setup, asset compilation, registration.
                    Non-zero exit unwinds the install.

Optional dependencies are tolerated: if install.sh / postinstall / extraction
fails for a slug declared in optionalDependencies, the failure is logged and
the install continues.

`add`

adompkg add <owner>/<slug>[@version] [...] [--dev|-D|--peer|-P] [--org <slug>]

Edit the local package.json AND install the package(s). Packages are
identified by <owner>/<slug> (a bare <slug> works if globally unique).
Defaults to "dependencies"; --dev writes to devDependencies; --peer writes to
peerDependencies. All three sections install locally so you can develop
against them; the peer section is just metadata for downstream consumers.

If the published package declares scope="dev", a bare 'adompkg add' routes
to devDependencies automatically.

Examples:
  adompkg add adom/mouser              # latest -> dependencies, installed
  adompkg add adom/mouser@^2.0.0       # explicit spec
  adompkg add adom/style-guide -D      # devDependency
  adompkg add adom/symbol -P           # peerDependency (host you augment)

Flags:
  --dev, -D         write to devDependencies and install with --dev
  --peer, -P        write to peerDependencies
  --org <slug>      install from a specific org's package namespace

`uninstall`

adompkg uninstall <owner>/<slug> [--force] [--no-prune] [--prune]

Remove a package and (for non-meta packages) prune now-orphan dependencies.
Refuses to remove a package that other installed packages still depend on
unless --force is set.

Flags:
  --force           remove even if other packages depend on it
  --no-prune        do not remove orphaned dependencies
  --prune           force prune even for meta packages (default: keep)

`publish`

adompkg publish [--version <v>] [--org <slug>] [--tag <t>] [--private|--public] [--no-source] [--yes|-y]

Build a tarball from the current directory and POST it to the registry. The
package is owned by <owner>/<slug>: the owner is your username, or the org
passed via --org (or chosen at the interactive "Publish as" prompt).

The current directory must contain a package.json with at minimum:
  slug, version, type, description, dependencies

For 'app' and 'skill' types, install.sh and uninstall.sh are also required.

Interactive prompts (TTY only — skipped with --yes, in non-TTY/CI, or when the
corresponding flag was already supplied):
  "Publish as"  pick your account or one of your orgs as the owner (uses
                GET /api/v1/me/orgs). Skipped when --org is passed.
  "Visibility"  public or private. Skipped when --public/--private is passed.

Visibility (on first publish only — subsequent publishes inherit the
page's existing setting):
  - public  (default): anyone can install and view the wiki page
  - private + --org X: only members of org X can install / view
  - private (no org): only the author can install / view

Use --no-source if you don't want your project tree pushed to the wiki
page's git repo (the tarball still uploads — installs still work — but
the Files tab stays minimal). Useful for proprietary apps whose code
should not be browseable.

Flags:
  --version <v>     override the version in package.json for this publish
  --org <slug>      publish into an org namespace (requires membership); the
                    org becomes the package owner. Skips the "Publish as" prompt.
  --tag <t>         apply a dist-tag (latest / beta / next / custom). Defaults
                    to 'latest' for non-prerelease versions.
  --private         create the page as private (first-publish only)
  --public          create the page as public (first-publish only; default)
  --no-source       skip the post-publish source push to the page git repo
  --yes, -y         non-interactive: never prompt, use flags/defaults

Lifecycle hooks (defined in package.json's "scripts" object):
  prepublish        runs in the project dir before any network or tarball
                    work. Use for code-gen, builds, asset generation. Non-
                    zero exit aborts the publish.

Requires authentication. Container API key (/var/run/adom/api-key) should be picked up automatically. Set ADOMPKG_TOKEN to override.

`list`

adompkg list

List installed packages and their versions, types, owning orgs, and number of
declared dependencies.

`why`

adompkg why <owner>/<slug>

Explain why a package is installed by walking the dependency graph BACKWARDS.
Shows each parent package that depends on <slug>, recursing all the way up
to root packages (the ones nothing else depends on). Roots are marked
"(root)"; duplicate subtrees collapse to "(see above)"; dev installs carry
a "[dev]" marker.

Example:
  $ adompkg why adom-lbr
  [email protected]
  ├── [email protected] (root)
  └── [email protected] (root)

`link`

adompkg link <owner>/<slug> [<path>]

Point an installed package at a local dev checkout instead of the extracted
tarball. Swaps the trunk symlink at ~/project/adom_modules/<slug>/ to
point at <path> (defaults to cwd). Because every install target (binary
on PATH, ~/.claude/skills/<slug>/, etc.) was created as a symlink INTO
the modules dir, downstream targets follow automatically — no separate
relinking needed.

The previous extracted tree is moved to ~/project/adom_modules/.link-stash/
so 'adompkg unlink' can restore it without re-downloading.

The path must contain a package.json whose slug matches the argument.
Refuses to mis-route otherwise.

Example dev loop:
  cd ~/work/adom-mouser
  adompkg link adom-mouser
  # edit files; binaries on PATH and skills in ~/.claude/skills/ now
  # reflect your dev checkout immediately.

Use 'adompkg unlink adom-mouser' to revert.

`unlink`

adompkg unlink <owner>/<slug>

Restore an 'adompkg link'-ed package to its real install. Removes the
symlink at ~/project/adom_modules/<slug>/ and, if available, restores
the previous extracted tree from ~/project/adom_modules/.link-stash/.

If no stash is available, you'll need to run 'adompkg install <slug>'
to reinstall.

Registry

`search`

adompkg search <query>

Search the wiki's FTS index across titles, briefs, READMEs, and tags.

`info`

adompkg info <owner>/<slug> [--org <slug>]

Show the latest manifest plus dist-tags and version history for a package.
For deeper detail (including reverse-deps and tarball size), use 'adompkg view'.

`view`

adompkg view <owner>/<slug>[@version] [--org <slug>]

Show the full manifest, all published versions, dist-tags, integrity SHA,
tarball size, deprecation status, dependencies, and reverse-dependencies.

`outdated`

adompkg outdated [--json] [--quiet|-q]

Check installed packages for available updates. Compares installed versions
against the registry's latest.

Flags:
  --json     output JSON: {"outdated": [{slug, installed, latest}, ...]}
  --quiet    one-liner summary, exit 1 if anything is outdated (for hooks)

`update`

adompkg update [<owner>/<slug> ...] [--org <slug>]

Resolve and install the latest versions of one or more installed packages.
With no arguments, updates everything installed.

Examples:
  adompkg update                 # update all installed packages
  adompkg update adom/mouser     # update one package

Publishing

`init`

adompkg init <slug> [--type app|skill|bootstrap] [--description "..."] [--needs-sudo] [--yes]

Scaffold a new package source directory. Without --yes, prompts for the
missing fields interactively.

Examples:
  adompkg init my-tool
  adompkg init my-skill --type skill --yes
  adompkg init my-bundle --type bootstrap --description "Curated bundle" --yes

`images`

Adding images & video to your page (hero + screenshots)

Every page is a git repo; images live as committed files in it. To show them:

1. PUT THE IMAGE IN THE REPO. Pick ONE binary-safe method:
   - Easiest: keep images in your project dir and run 'adompkg publish'
     (the default --source push commits your tree, images and all).
   - Or 'git push' straight to the page repo (git stores binary natively).
   - Or the upload API:
       curl -F "[email protected];filename=hero.png" \\
         <registry>/api/v1/pages/<slug>/files -H "Authorization: Bearer <tok>"
     JSON callers MUST base64-encode binaries:
       {"files":[{"path":"hero.png","content":"<base64>","encoding":"base64"}]}
   ⚠️ Never put raw binary bytes in a JSON string "content" without
     encoding:"base64" — it gets utf8-mangled and the image renders broken.

2. SET THE HERO in page.json (shown big at the top of the Overview):
       "hero": { "type": "image", "path": "hero.png" }
   Use "type":"video" with an .mp4/.webm path for a video hero.

3. EMBED SCREENSHOTS in README.md with relative paths — they resolve to the
   page's files automatically:
       ![Main view](main-view.png)

Supported: png, jpg, gif, webp, svg (images); mp4, webm (video hero).
After uploading, the page reindexes automatically.

`pack`

adompkg pack [--out <file>]

Build the publishable tarball locally without uploading. Useful for
inspecting what would be published.

Flags:
  --out <file>      write the tarball to <file> (default: <slug>-<version>.tgz)

`version`

adompkg version <bump>

Bump the version in package.json and write the new version back. The bump
argument can be one of:
  patch        1.2.3   -> 1.2.4
  minor        1.2.3   -> 1.3.0
  major        1.2.3   -> 2.0.0
  premajor     1.2.3   -> 2.0.0-beta.0
  preminor     1.2.3   -> 1.3.0-beta.0
  prepatch     1.2.3   -> 1.2.4-beta.0
  prerelease   1.2.3-beta.0 -> 1.2.3-beta.1
               1.2.3        -> 1.2.4-beta.0
  <semver>     explicit value, e.g. 1.5.0

`deprecate`

adompkg deprecate <owner>/<slug>@<version> "message"

Mark a specific version as deprecated. The message is shown by 'install' and
'audit'. Empty message clears the deprecation.

Examples:
  adompkg deprecate adom/[email protected] "Use 2.x — 1.x is end-of-life"
  adompkg deprecate adom/[email protected] ""    # un-deprecate

Admin

`audit`

adompkg audit [--layout]

Report any installed package that has been deprecated upstream. Exits non-zero
if any deprecations are found.

With --layout, instead reports whether install targets (binaries in
~/.local/bin or /usr/local/bin, skills in ~/.claude/skills/) are symlinks
back into ~/project/adom_modules/<slug>/ (the Adom convention) or real
copies (drift). Use this to spot packages whose install.sh used cp
instead of ln -sfn — those edits-in-modules-dir won't take effect and
reinstalls will clobber any in-place fixes.

Flags:
  --layout         report symlink-vs-copy status of install targets

`ci`

adompkg ci [--frozen]

Clean reinstall every package listed in .lock.json. Errors if --frozen and
no lock file is present. Intended for repeatable CI environments.

`bootstrap`

adompkg bootstrap [<meta-slug>]

Thin alias for 'adompkg install <meta-slug>'. Defaults to adom-core when
no slug is passed. Kept for back-compat with the original bootstrap
flow; new code should just call 'adompkg install <meta-slug>' directly.

A bootstrap package is any wiki package of type "bootstrap" — a curated
dep list that sets up a role's worth of tooling in one shot. Examples:
  adompkg bootstrap                 # adom/core (standard set)
  adompkg bootstrap acme/baseline   # a private org-owned baseline

`whoami`

adompkg whoami

Print the currently authenticated user (name, email, ID, and orgs). Exits
non-zero if no token is configured.

`help`

adompkg help [<command>]

Show top-level help, or detailed help for a specific command.