# AgentsMarkdown CLI

Install the CLI directly from this site or use the package name `@agentsmarkdown/cli`. The canonical command is `agmd`; `agentsmarkdown` is the long-form alias.

```bash
curl -fsSL https://agentsmarkdown.com/install.sh | sh
```

```bash
agmd commands --json
agmd docs create "Launch notes" -f notes.md
agmd docs cat "https://agentsmarkdown.com/d/DOC_ID?key=SHARE_KEY"
agmd docs push "https://agentsmarkdown.com/d/DOC_ID?key=SHARE_KEY" -f notes.md --label "tightened intro"
```

Share URLs work without setup. For account-owned documents, store a mere.world app-session token:

```bash
agmd login
agmd whoami
```

Use `AGENTSMARKDOWN_URL` or `AGMD_URL` for a non-production origin. Use `agmd login --token asess_...`, `AGENTSMARKDOWN_TOKEN`, or `AGMD_TOKEN` to supply a token manually.

Direct downloads are available at `https://agentsmarkdown.com/downloads/agmd` with checksum `https://agentsmarkdown.com/downloads/agmd/checksum`.

Machine-readable discovery is available from `agmd commands --json` and `https://agentsmarkdown.com/api/cli/commands`.

| Command | Auth | Risk | Summary |
| --- | --- | --- | --- |
| `agmd commands --json` | none | read | Print the machine-readable command manifest. |
| `agmd login` | session | external | Sign in with the mere.world device flow and store an AgentsMarkdown app-session token. |
| `agmd whoami` | session | read | Show the current human account resolved by the stored or supplied token. |
| `agmd logout` | session | write | Revoke the current app-session token when possible and clear local CLI config. |
| `agmd config [set <base-url|token|author> <value>]` | none | write | Read or update local CLI configuration. |
| `agmd completion <bash|zsh|fish>` | none | read | Generate shell completion for the agmd command. |
| `agmd docs list` | session | read | List documents owned by the current human account. |
| `agmd docs create <title> [-f file]` | share | write | Create a document from a file, stdin, or a generated heading. |
| `agmd docs info <doc-url-or-id>` | share | read | Read document metadata and your effective role. |
| `agmd docs cat <doc-url-or-id>` | share | read | Print canonical markdown to stdout. |
| `agmd docs pull <doc-url-or-id> [-o file]` | share | read | Fetch markdown and remember the document version for later conflict checks. |
| `agmd docs push <doc-url-or-id> -f file [--force] [--label text]` | share | write | Replace document markdown with version-aware conflict protection. |
| `agmd docs delete <doc-url-or-id> --yes` | share | destructive | Delete a document with owner access. |
| `agmd comments add <doc-url-or-id> <text> [--line N]` | share | write | Add a comment, optionally anchored to a markdown line. |
| `agmd comments list <doc-url-or-id>` | share | read | List comments and replies. |
| `agmd comments resolve <doc-url-or-id> <comment-id>` | share | write | Resolve a comment thread. |
| `agmd suggestions add <doc-url-or-id> (--replace old --with new | --append text)` | share | write | Create a suggested edit without changing canonical markdown. |
| `agmd suggestions list <doc-url-or-id>` | share | read | List pending and decided suggestions. |
| `agmd suggestions accept <doc-url-or-id> <suggestion-id...>` | share | write | Accept one or more suggestions. |
| `agmd suggestions reject <doc-url-or-id> <suggestion-id...>` | share | write | Reject one or more suggestions. |
| `agmd shares create <doc-url-or-id> <view|comment|suggest|edit>` | share | write | Create a scoped capability link. |
| `agmd shares list <doc-url-or-id>` | share | read | List share links with owner access. |
| `agmd shares revoke <doc-url-or-id> <secret>` | share | write | Revoke a capability link. |
| `agmd publish <doc-url-or-id>` | share | write | Publish a document to /pub/{id}. |
| `agmd unpublish <doc-url-or-id>` | share | write | Remove the public published copy. |
| `agmd claim <doc-url>` | session | write | Claim an anonymous owner-link document into the current human account. |
| `agmd history <doc-url-or-id>` | share | read | List document revisions. |
| `agmd events <doc-url-or-id> [--since N]` | share | read | Read document activity events. |
| `agmd watch <doc-url-or-id> [--since N] [--json]` | share | read | Long-poll document activity events. |