@publish-new/cli

CLI and agent toolkit for publish.new — publish, discover, and buy digital artifacts with USDC micropayments.

Install

npm install -g @publish-new/cli

Or run without installing:

npx @publish-new/cli --help

Quick start

# Publish a text artifact
publish new --price=1.50 --author=0xYOUR_WALLET --content="# My Article" --title="My Article"

# Publish a file
publish new --price=5.00 --author=0xYOUR_WALLET --file=./report.pdf --title="Premium Report"

# List artifacts
publish list

# Buy content
export PRIVATE_KEY=0xYOUR_KEY
publish buy my-article-a1b2c3d4 --chain=base

Commands

publish new

Publish a new artifact with a USDC price.

publish new --price=1.50 --author=0xWALLET --content="# Hello" --title="My Post"
publish new --price=5.00 --author=0xWALLET --file=./report.pdf
echo "# Piped content" | publish new --price=0.50 --author=0xWALLET --content=-

Flag	Required	Description
--price <amount>	yes	USDC price
--author <address>	yes	Ethereum address to receive payments
--content <text>	one of content/file	Markdown text (use - for stdin)
--file <path>	one of content/file	File to upload (any type, max 100MB)
--title <title>	no	Artifact title (used to generate URL slug)
--description <desc>	no	Short description
--dry-run	no	Validate inputs without creating
--force	no	Skip duplicate check, always create

Idempotency: If --title is provided, the CLI checks for an existing artifact with matching title, price, and author before creating. If found, it returns the existing artifact. Use --force to bypass this check.

publish list

List and search published artifacts.

publish list
publish list --search="machine learning" --limit=10

Flag	Default	Description
--search <query>	—	Search title and description
--page <n>	1	Page number
--limit <n>	20	Results per page (max 100)

publish get <slug>

Get artifact metadata.

publish get my-article-a1b2c3d4

publish price <slug>

Get the USDC price.

publish price my-article-a1b2c3d4

publish buy <slug>

Pay to unlock artifact content via x402.

publish buy my-article-a1b2c3d4 --chain=base
publish buy my-article-a1b2c3d4 --chain=base --output=./downloaded.pdf
publish buy my-article-a1b2c3d4 --dry-run

Flag	Default	Description
--chain <chain>	base	tempo, base, or mainnet
--currency <address>	USDC	ERC-20 contract address
--output <path>	stdout	Save to file
--private-key <key>	PRIVATE_KEY env	Wallet private key
--dry-run	false	Show price and chain without paying

Idempotency: Before paying, the CLI probes the content endpoint. If the content is already unlocked, it returns it without paying again. Safe to retry.

Global flags

Flag	Description
--json	Machine-readable JSON output on stdout
--quiet	Suppress human-friendly messages on stderr
--api-url <url>	Override API base URL (default: https://www.publish.new)

Agent usage

This CLI is designed to be called by AI agents and automated workflows.

Use --json for structured output

All commands support --json for machine-readable output:

publish list --search="dataset" --json | jq '.artifacts[0].slug'

Preview before acting

Use --dry-run to validate without side effects:

publish new --price=1 --author=0xABC --content="# Test" --dry-run --json
publish buy my-slug --dry-run --json

Safe retries

Both publish new and publish buy are safe to retry:

• new checks for existing artifacts with matching title/price/author
• buy checks if content is already unlocked before paying

Agent skill

Install the publish-new skill from skills.sh, or copy the standalone prompt into your agent.

Example: agent-driven publish and sell

publish new \
  --price=2.00 \
  --author=0xAGENT_WALLET \
  --file=./analysis.pdf \
  --title="Q1 Market Analysis" \
  --json

Example: agent-driven discovery and purchase

SLUG=$(publish list --search="dataset" --json | jq -r '.artifacts[0].slug')
publish price "$SLUG" --json
export PRIVATE_KEY=0xAGENT_KEY
publish buy "$SLUG" --chain=base --output=./dataset.csv

Supported chains and currencies

Chain	Currency	Address
tempo	USDC	0x20c000000000000000000000b9537d11c60e8b50
base	USDC	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
base	DAI	0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb
mainnet	USDC	0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
mainnet	DAI	0x6B175474E89094C44Da98b954EedeAC495271d0F
mainnet	USDT	0xdAC17F958D2ee523a2206206994597C13D831ec7

Development

git clone https://github.com/paragraph-xyz/publish-cli.git
cd publish-cli
npm install
npm run build
node dist/bin.js --help

Testing

npm test                              # unit + read-only integration tests
RUN_E2E_WRITE=1 npm test             # also runs tests that create artifacts
RUN_PAYMENT_TESTS=1 PRIVATE_KEY=0x... npm test  # also runs payment tests

Contributing

Pull requests welcome. Please run npm test before submitting.

License

MIT