# CLI Manage posts, publications, subscribers, and coins from the command line. Built for humans, agents, and CI. The Paragraph CLI is a command-line tool for managing posts, publications, subscribers, and coins. It works for both human and programmatic (agent) usage. **Prerequisites**: Node.js version 18 or higher (not needed for the Homebrew install). ## Install ### npm ``` npm install -g @paragraph-com/cli ``` ### Homebrew ``` brew tap paragraph-xyz/tap && brew install paragraph ``` ## Authentication Get your API key in the app at [app.paragraph.com](https://app.paragraph.com/) under **Settings -> Publication -> Developer**. ### Authenticate ``` paragraph login ``` Or provide the key directly: ``` paragraph login --token ``` ### Verify ``` paragraph whoami ``` For CI or agent environments, you can pipe the token or set an environment variable: ``` echo "" | paragraph login --with-token PARAGRAPH_API_KEY= paragraph post list ``` Credentials are stored in `~/.paragraph/config.json` (mode 0600). ## Quick examples ``` paragraph post create --title "My Post" --file ./draft.md paragraph post publish my-post paragraph post list paragraph search post --query "ethereum" ``` Run `paragraph --help` for all commands, or `paragraph --help` for details on any command. Using an AI agent like Claude Code or Cursor? Install the [Paragraph CLI skill](https://docs.paragraph.com/developers/agent-skills) to teach it how to use the CLI: ``` npx skills add paragraph-xyz/skill --skill paragraph-cli ``` ## Command reference ### Posts #### List posts ``` paragraph post list paragraph post list --status draft paragraph post list --limit 50 --cursor # List posts from any publication (public, no auth required) paragraph post list --publication ``` #### Get a post Accepts an ID, URL, or `@publication/slug`: ``` paragraph post get paragraph post get @yearn/some-post-slug paragraph post get https://paragraph.com/@yearn/some-post-slug ``` Extract a single field (raw value to stdout, pipeable): ``` paragraph post get --field markdown > post.md paragraph post get --field title ``` #### Create a post Creates a draft by default: ``` paragraph post create --title "My Post" --text "# Hello World" paragraph post create --title "My Post" --file ./draft.md cat draft.md | paragraph post create --title "From Stdin" paragraph post create --title "Post" --text "Content" --subtitle "Summary" --tags "web3,defi" ``` #### Update a post ``` paragraph post update --title "New Title" paragraph post update --file ./updated.md --tags "new,tags" ``` #### Post lifecycle ``` paragraph post publish paragraph post publish --newsletter # publish + email subscribers paragraph post draft # revert to draft paragraph post archive ``` #### Preview and test ``` paragraph post publish --dry-run paragraph post delete --dry-run paragraph post test-email # send test email (drafts only) ``` #### Delete a post ``` paragraph post delete paragraph post delete --yes # skip confirmation ``` #### Browse posts ``` paragraph post by-tag defi --limit 20 paragraph post feed --limit 10 ``` #### Shortcuts Top-level shortcuts for common operations: ``` paragraph create --title "Quick Post" --text "Content" paragraph update my-post-slug --title "Updated" paragraph delete my-post-slug --yes ``` ### Publications ``` paragraph publication get @variantwriting paragraph publication get blog.variant.fund paragraph publication get ``` ### Search ``` paragraph search post --query "ethereum" paragraph search blog --query "web3" ``` ### Subscribers ``` paragraph subscriber list --limit 100 paragraph subscriber count paragraph subscriber add --email user@example.com paragraph subscriber add --wallet 0x1234...abcd paragraph subscriber import --csv subscribers.csv ``` ### Coins ``` paragraph coin get paragraph coin popular --limit 10 paragraph coin search --query "test" paragraph coin holders --limit 50 paragraph coin quote --amount ``` ### Users ``` paragraph user get paragraph user get 0x1234... # by wallet address ``` ## Agent and programmatic usage The CLI is designed for use by AI agents and scripts. ### JSON output All commands support `--json`. Data goes to **stdout**, status messages to **stderr**: ``` paragraph --json post list | jq '.data[0].title' paragraph --json post get | jq '.markdown' paragraph --json search post --query "web3" | jq '.length' ``` Paginated commands return: ``` { "data": [{ "id": "...", "title": "..." }], "pagination": { "cursor": "abc123", "hasMore": true }} ``` Single-item commands return the object directly: ``` { "id": "...", "title": "...", "markdown": "..." } ``` ### Structured errors In `--json` mode, errors are structured JSON on **stderr** with a non-zero exit code: ``` { "error": "Not found.", "code": "NOT_FOUND", "status": 404 } ``` Error codes: `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `RATE_LIMITED`, `SERVER_ERROR`, `REQUEST_FAILED`, `CLIENT_ERROR`, `UNKNOWN`. ### Non-interactive safety - `delete` requires `--yes` in non-TTY environments - `login` supports `--with-token` for stdin piping and `--token` for direct input - Destructive commands support `--dry-run` - Set `PARAGRAPH_NON_INTERACTIVE=1` or `CI=true` to force CLI mode ### Environment variables | Variable | Purpose | | --- | --- | | `PARAGRAPH_API_KEY` | API key (alternative to `login`) | | `PARAGRAPH_API_URL` | Custom API base URL | | `PARAGRAPH_NON_INTERACTIVE` | Set to `1` to disable TUI | | `CI` | Set to `true` to disable TUI | ## Interactive TUI Running `paragraph` with no arguments launches an interactive terminal UI with menus, scrollable lists, and keyboard navigation. The TUI is disabled automatically when: - `--json`, `--help`, or `--version` flags are used - stdout is not a TTY (e.g., piped output) - `CI=true` or `PARAGRAPH_NON_INTERACTIVE=1` is set ## Resources [**View on GitHub** \ Explore the source code or report issues.](https://github.com/paragraph-xyz/paragraph-cli) [**npm package** \ View on npm.](https://www.npmjs.com/package/@paragraph-com/cli) [TypeScript SDK\ \ Install the Paragraph SDK and query publications, posts, coins, and user profiles with full type safety.](https://docs.paragraph.com/developers/sdk) [MCP server\ \ Connect AI agents to Paragraph via the Model Context Protocol.](https://docs.paragraph.com/developers/mcp)