Provider Commands

Every command that talks to a package manager follows the same pattern: hams <provider> <verb> [args]. Each provider registers its own set of verbs, mapped to the tool it wraps — brew, pnpm, apt, bash, you name it.

The routing pattern


hams <provider> <verb> [args] [--hams-flags] [-- <passthrough>]

<provider> — the provider name (brew, pnpm, apt, bash, …)
<verb> — a verb supported by that provider (see below)
[args] — whatever the verb needs (package name, file path, etc.)
--hams-* — hams-specific flags, never forwarded to the wrapped tool
-- — everything after this point goes straight to the wrapped tool, untouched

The verbs most providers support

Verb	What it does	Example
`install` / `add`	Install a package and record it in the Hamsfile	`hams brew install htop`
`remove` / `uninstall`	Remove a package and drop it from the Hamsfile	`hams brew remove htop`
`list`	List packages managed by this provider	`hams brew list`
`enrich`	Add metadata (tags, intro) to an already-recorded package	`hams brew enrich htop`

Not every provider supports every verb. hams git clone <remote> <path> matches plain git clone’s shape (no leading add or install); bash uses run. Check the individual provider doc for specifics.

Examples


# Homebrew: install a formula
hams brew install htop
 
# pnpm: install globally
hams pnpm add serve
 
# npm: install globally
hams npm install --global prettier
 
# Homebrew: remove
hams brew remove htop
 
# See what's managed under Homebrew
hams brew list
 
# Attach metadata to an existing entry
hams brew enrich htop --hams-tag=cli --hams-intro="An interactive process viewer"

The `--hams-` flag convention

To avoid colliding with whatever flags the wrapped tool defines, every flag hams introduces is prefixed --hams-. hams strips them off before handing the rest to brew / pnpm / etc.

Flag	What it does
`--hams-tag=<tags>`	Tag the resource. Comma-separated for multiples
`--hams-intro=<text>`	A one-line description written into the Hamsfile
`--hams-local`	Write to `<Provider>.hams.local.yaml` (not committed) instead of the main Hamsfile


# Install ripgrep tagged 'search,cli' with a description
hams brew install ripgrep --hams-tag=search,cli --hams-intro="Fast recursive grep alternative"
 
# A tool that's only for this machine, not the shared store
hams brew install zoom --hams-local

Passing through with `--`

If the wrapped tool has a flag you want to pass along, but you don’t want hams to interpret it as its own, put -- in between.


# The --verbose goes to brew, not to hams
hams brew install htop -- --verbose
 
# Similarly, --save-dev goes to pnpm
hams pnpm add typescript -- --save-dev

To see what verbs and flags a specific provider supports, run hams <provider> --help. You can also browse the Providers chapter for the per-provider documentation.