> ## Documentation Index
> Fetch the complete documentation index at: https://www.openpmm.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenPMM CLI

> Use the public OpenPMM API from a terminal, script, or coding agent to publish Posts.

The OpenPMM CLI is the first-party client for the public `/v1` API. Use it
from a terminal, shell script, CI job, or coding agent.

The CLI has no database, provider credential, worker, or deployment access. It
does not call private application routes.

<Note>
  The public [`@openpmm/cli` package](https://www.npmjs.com/package/@openpmm/cli) is available on npm. Its source, tests, and release workflow are also public.
</Note>

<CardGroup cols={2}>
  <Card title="View source on GitHub" icon="github" href="https://github.com/OpenPMM/cli">
    Audit the complete source, tests, and release workflow.
  </Card>

  <Card title="Authenticate the CLI" icon="key" href="/docs/cli/authentication">
    Sign in through your browser and approve a Workspace.
  </Card>
</CardGroup>

## Install or run once

Run the CLI without an installation:

```bash theme={null}
npx -y @openpmm/cli@0.5.0 --help
```

Or install the `openpmm` command globally:

```bash theme={null}
npm install --global @openpmm/cli
openpmm --version
```

Node.js 22 or newer is required.

If the global install succeeds but `openpmm` is not found, compare the npm bin
directory with your `PATH`:

```bash theme={null}
npm prefix --global
printf '%s\n' "$PATH"
```

Add `<npm-prefix>/bin` to `PATH`, or use the pinned `npx` command.

## Run from source

You can also run the audited source:

```bash theme={null}
git clone https://github.com/OpenPMM/cli.git
cd cli
node src/openpmm.js --help
```

## Common workflow

```bash theme={null}
openpmm signup create \
  --email publisher@example.com \
  --workspace-name "Product Marketing" \
  --authorize-cli

openpmm auth login --resume

openpmm posts create \
  --when draft \
  --group launch \
  --channel x \
  --body 'Draft copy'
openpmm posts list --view drafts --json
openpmm posts publish \
  --post send_01JABCDEF \
  --post-version 1 \
  --destination dest_01JABCDEF \
  --yes \
  --json
```

The signup command does not need an API key. It opens the returned `signup_url`
and returns immediately. After browser approval, `auth login --resume` stores
the resulting credential and Workspace.
See [Create an account](/docs/cli/signup).

Run `openpmm --help` to see the command tree. Run
`openpmm <command> --help` to see its API operation, scope, side effects,
input forms, complete flag list, output modes, exit codes, and a copyable
example.

Run a read-only compatibility check before automation:

```bash theme={null}
openpmm doctor --json
```

It reports the CLI and API versions, authentication context, selected
Workspace, scopes, ready Destinations, and credential file permissions. The
`workflows.draft.ready` field checks the requirements for draft creation. The
`workflows.publish.ready` field also requires a ready Destination. A missing
Destination does not block draft creation. The command never prints the API
key.

For an agent workflow, treat `openpmm` as the complete CLI interface. Do not
read its credential file or use its key in another client. See
[Agent workflow](/docs/cli/agent-workflow).

## Customize the Writing Assistant

Read all seven effective Workspace refinement options:

```bash theme={null}
openpmm writing-assistant settings show --json
```

Save the response's `actions` object in a JSON request file, then edit the
titles, full prompt templates, and icon keys. Keep all seven action keys and
send the complete replacement:

```bash theme={null}
openpmm writing-assistant settings update \
  --file writing-assistant-settings.json \
  --json
```

The CLI reads the current ETag before the update. Use `--etag` to pin an update
to a version that you read earlier. See [Refine post copy](/docs/guides/refine-post-copy)
for the web workflow and system prompt disclosure.

## Public compatibility contract

Command names, flags, JSON fields, stdout and stderr behavior, and exit codes
are public interfaces. Before `1.0`, a minor release can contain breaking
changes. After `1.0`, breaking changes require a major release and a documented
deprecation when a safe compatibility path exists.