CLI overview

Every palm command is a verb followed by its arguments. For install and remove, the source comes first.

palm <verb> [source] [[kind:]name...] [options]

Command	Meaning
`palm install mattpocock/skills`	List what a source offers. Writes nothing.
`palm install mattpocock/skills tdd grill-me`	Install two entities from one source and declare the source in `palm.yaml`.
`palm install anthropics/claude-plugins-official mcp:context7`	Name the kind when one name means two kinds in that source.
`palm install`	Make the disk match `palm.yaml` and the lock.
`palm remove tdd`	Remove an entity by name.
`palm get skills`	List installed skills.
`palm describe .mcp.json`	Show which entities wrote a file.
`palm install mattpocock/skills handoff -g`	The same verbs in your home directory.

Verbs

Verb	Aliases	Meaning
`init`		write palm.yaml with the targets found here
`install`	`add`, `i`	install from a source; bare, sync with palm.yaml
`remove`	`uninstall`, `rm`	delete exactly what palm wrote for some entities
`update`	`up`	move sources to newer commits within their refs
`check`		verify palm.yaml, the lock and the files (CI gate)
`get`	`list`, `ls`	list what is installed, the sources or the targets
`describe`	`info`	show one entity, source, target or file
`create`	`new`	write a template into your own source and install it

Utilities

Utility	Arguments	Meaning
`migrate`		convert a palm 0.1 project to the palm 0.2 files
`completion`	`<shell>`	print a shell completion script
`cache`	`clean`	delete the cache of checkouts and indexes

palm help <command> prints the same text as palm <command> --help. --help fits on one screen and lists no exit codes. This site lists them.

Kinds

install and remove take a kind as a prefix, kind:name, only when one name means two kinds in a source. get and describe take a kind as a word, singular, plural or short.

Kind	Short name	Other words	Verbs
`skill`	`sk`	`skills`, `command`, `commands`, `cmd`, `prompt`, `prompts`	`get`, `describe`, `create`
`agent`	`ag`	`agents`, `subagent`, `subagents`	`get`, `describe`, `create`
`instruction`	`ins`	`instructions`, `rule`, `rules`	`get`, `describe`, `create`
`hook`	`hk`	`hooks`	`get`, `describe`, `create`
`mcp`		`mcps`, `mcp-server`, `mcp-servers`, `server`, `servers`	`install`, `get`, `describe`
`plugin`	`pl`	`plugins`, `bundle`, `bundles`	`get`, `describe`
`source`	`src`	`sources`, `origin`, `origins`, `orig`	`get`, `describe`
`target`	`tg`	`targets`	`get`, `describe`
`all`			`get`

cmd, command and commands mean skill, with a note, because commands install as skills. origin and orig mean source for one release.

Global options

Every command accepts these options.

Option	Meaning
`-g, --global`	use ~/.palm/palm.yaml and the harness home directories
`--dry-run`	show what would change; write nothing
`--force`	replace files you changed or that palm does not own
`-y, --yes`	accept plan confirmations (never consents to programs)
`--allow-exec <list>`	allow programs: hook:x@source=sha256:hash,… or all
`--offline`	use the cache only; no network
`--json`	one JSON document on stdout; everything else on stderr
`--secrets <policy>`	env-ref (default) or literal, for secrets you type
`-V, --version`	print the palm version
`-h, --help`	display help for command

What the options do

Option	Detail
`-g`	Works with every verb. The global scope has its own `~/.palm/palm.yaml`, lock and sources. See scopes.
`--dry-run`	Resolves and renders everything, prints `would install`, `would restore` and `would remove` lines, and writes nothing in the scope. palm may still fetch into its cache.
`--force`	Replaces a file palm did not write or you changed since palm wrote it. Never overrides hidden Unicode, an unresolvable hook reference, a literal secret from a source, the git worktree guard for literal secrets, or another source’s ownership of an entity.
`--yes`	Accepts pickers and plan confirmations, such as `Apply 2 changes?`. It never consents to a program.
`--allow-exec`	Consents to programs by exact hash, as printed by the consent error. `all` works only on a terminal. See consent.
`--offline`	Reads sources from the cache only. A commit that is not cached fails with `E_NETWORK`.
`--json`	See JSON output.
`--secrets literal`	Writes typed secret values instead of references, and records `secrets: literal` on the entry. See secrets.
`--local`	Stops with a usage error in 0.2. `palm.local.yaml` arrives in 0.3; until then use `-g` for a personal entity, and the harness’s own settings to switch off a team entity for yourself.

There is no --verbose and no --no-color. Set PALM_DEBUG=1 for debug lines and NO_COLOR=1 to turn colour off.

Prompts

palm prompts only on a terminal, and every prompt has a flag. Every yes or no question uses the same [y/N] text prompt, and Enter answers no.

Prompt	Default	Without a terminal
Allow these programs to run?	no	`E_UNTRUSTED_EXEC`, naming the `--allow-exec` line
Apply the update plan	no	`E_NON_INTERACTIVE`, naming `--yes`
Change a declared source’s ref	no	`E_NON_INTERACTIVE`, naming `--yes`
Clean the cache	no	`E_NON_INTERACTIVE`, naming `--yes`
A secret value under `--secrets literal`	none	`E_NON_INTERACTIVE`, naming `--secrets env-ref`
Which kind a name means, when a source offers it as two	none	`E_AMBIGUOUS`, listing the `kind:name` forms
The detected targets, in `palm init` without `--target`	the detected set	the detected set is written

palm never asks which source to use; that comes from the command line and palm.yaml. It asks about targets only in palm init and in a global install that detects no harness.

Output

Data goes to stdout. Each status line starts with a symbol.

Symbol	Meaning
`+`	installed or added
`-`	removed
`~`	updated or re-rendered
`↺`	restored: a missing generated file written again
`=`	unchanged: the render equals the lock and the disk equals the render, on every target; reports print these as one count line
`⊘`	skipped for one target, with the reason; an in-repo source that `palm update` skips gets one line for the whole source
`x`	error or failed
`!`	warning, a modified file palm kept, or a partial install
`i`	information

Warnings are collected and printed once at the end, on stderr, under a Warnings heading. A note that applies to many rows prints once. An error comes last, as an x line with the message and then a hint that is a command you can paste. When the same command with another flag fixes the error, the hint repeats your command with that flag, and names every flag that must go together. Hints name sources as you declared them in palm.yaml, carry -g in the global scope, and write kind:name when a name is ambiguous. In the global scope, paths print as ~/....

Colour appears only when stdout is a terminal. NO_COLOR=1 turns it off.

JSON output

With --json, stdout holds exactly one JSON document and every other line goes to stderr. A list comes as { "items": [...] }, and every document has a warnings array. An error is { "error": { "code", "message", "hint" }, "warnings": [] }, and the exit code still reports it. A dry run reports statuses such as would-install and would-remove, and a version is an object { "ref", "sha" }.

$ palm get skills --json
{
  "items": [
    {
      "kind": "skill",
      "name": "tdd",
      "source": "mattpocock/skills",
      "ref": "^1.2",
      "resolved": "v1.2.3",
      "sha": "2c0db9046017ad90f70ed14046665fee10b122b9",
      "targets": [
        "claude"
      ],
      "files": [
        ".claude/skills/tdd/SKILL.md",
        ".claude/skills/tdd/references/mocking.md"
      ],
      "merged": []
    }
  ],
  "warnings": []
}
$ palm install mattpocock/skills tdd-coach --json
{
  "error": {
    "code": "E_NOT_FOUND",
    "message": "\"tdd-coach\" is not in source mattpocock/skills; did you mean tdd?",
    "hint": "palm install mattpocock/skills tdd --json"
  },
  "warnings": []
}

Exit codes

Code	Meaning
`0`	Success, including `--help`, `--version` and a bare `palm`. Warnings never change it.
`1`	Failure: a refusal, a failed or partial install, a modified file palm kept, or a failed check
`2`	Usage error: an unknown command, option or argument, a removed 0.1 command, or a 0.1 `palm.yaml`
`130`	Cancelled: Ctrl-C, Esc at a prompt, a declined source ref change, a declined program you named, or a declined new version of a trusted program

Exit codes and errors lists every error code with its fix.

Old commands

The palm 0.1 grammar works for one release as hidden aliases.

$ palm install origin mattpocock/skills
i palm install origin is now: palm install mattpocock/skills
i 1 note from indexing mattpocock/skills (see: palm describe source mattpocock/skills)
mattpocock/skills  v1.2.3 (2c0db90)   1 plugin, 5 skills
  plugin  mattpocock-skills   3 skills
  skill   tdd                 Test-driven development with red-green-refactor.
  skill   grill-me            Interview the user relentlessly about a plan.
  skill   handoff             Write a handoff note for the next session.
  skill   old-thing           An old skill kept for reference.
  skill   git-guardrails      Block dangerous git commands.
Nothing written. Install some:
    palm install mattpocock/skills tdd grill-me
    palm install mattpocock/skills --all
$ palm outdated
x palm outdated is now: palm update --dry-run
$ palm search tdd
x palm search is gone; find a repository (https://github.com/search?q=tdd+SKILL.md&type=code), then list it, for example: palm install mattpocock/skills; an MCP server comes from its README: pbpaste | palm install mcp --snippet -

The 0.1 form install skill tdd@mattpocock resolves the alias mattpocock against the declared sources, so mattpocock/skills matches, and runs. When no declared source matches, the hint is the palm install <source> <name> form, never palm migrate. The removed commands doctor, audit, outdated, why, find, search and config print one line naming the replacement and exit 2. Removed 0.1 flags print their replacement: --frozen prints palm check and runs it. Migrate from palm 0.1 maps each one.