PostNitro CLI

The PostNitro CLI creates on-brand social media posts — multi-slide carousels and single images — and schedules them to LinkedIn, Instagram, TikTok, and Threads, all from the command line. It’s a thin, scriptable wrapper over the Embed API, built for AI agents, automations, and scripts: every command takes flags or JSON in and prints JSON out (clean stdout on success, JSON error on stderr) — no colors, tables, or interactive prompts to parse around. It uses the same Embed API key and credits as the REST API and MCP server.

Quick Reference

Installation

# Install globally from npm (recommended)
npm install -g @postnitro/cli
postnitro --help
 
# Or run without installing
npx @postnitro/cli --help

Install as a skill

You can also install PostNitro as a skill for your AI coding agent — it teaches the agent to drive the CLI on your behalf:

npx skills add postnitro/postnitro-agent

For Claude Code specifically, you can instead add it as a plugin:

# in Claude Code
/plugin marketplace add postnitro/postnitro-agent
/plugin install postnitro@postnitro-agent

The skill is defined in SKILL.md at the repo root  (with a copy under skills/postnitro/); the Claude Code plugin manifests live in .claude-plugin/.

Authentication

Get an API key from PostNitro → Profile → Embed → Generate API Key (see Obtaining an API Key). Provide it in any of these ways (highest precedence first):

1. --api-key <key> on any command
2. POSTNITRO_API_KEY environment variable
3. Saved config — postnitro auth set-key <key> (stored at ~/.postnitro-cli/config.json)

postnitro auth set-key pn-xxxxxxxxxxxx   # save it once
postnitro auth status                    # check what's configured (key is masked)
postnitro auth clear                     # remove the saved key

Security: auth set-key stores your key in plaintext at ~/.postnitro-cli/config.json. Restrict its permissions, avoid shared machines, and use --api-key or POSTNITRO_API_KEY in CI.

Core concepts

Post type × content source. Creating a post is two independent choices:

Asynchronous by default. Creating a post kicks off a background job and returns an embedPostId. Add --wait to poll to completion and get the final output in one call, or poll manually with status / output.

embedPostId vs designId. Creation returns an embedPostId (the job). To schedule a post you need its designId (from the --wait result or output). Never pass an embedPostId to schedule — see carousel identifiers.

Editor link. Every completed post’s output includes an editorUrl — a deep link to open the design in the PostNitro editor.

JSON in / JSON out. Complex inputs can be passed inline as JSON (agent-friendly) or from a file; inline always wins. Every command prints JSON to stdout on success (exit 0) or a JSON error to stderr (exit 1).

Smart defaults. --template-id / --brand-id / --preset-id resolve in this order: explicit flag → saved default (defaults set) → auto-select when your workspace has exactly one candidate.

Global options

Available on every command:

Command reference

auth

Manage the saved PostNitro API key.

defaults

Save default templateId / brandId / presetId / responseType so create commands don’t need them every time.

postnitro defaults set --template-id tpl_123 --brand-id brd_456 --preset-id prs_789 --response-type PDF
postnitro defaults get

template

Browse available carousel templates.

postnitro template list --limit 20

brand

Manage brand kits (logo, name, handle stamped on designs). See the Brands API for full field definitions.

Options for create / update:

postnitro brand create --name "PostNitro" --handle "@postnitroai" --image "https://.../logo.png" --company-detail
postnitro brand create --data '{"name":"PostNitro","handle":"@postnitroai","image":"https://.../logo.png","isCompanyDetail":true}'

preset

Browse available AI generation presets (each bundles social platform, tone, audience, language, slide count, and model).

social

Manage connected social accounts. See the Social Accounts API for full field definitions.

carousel

Generate, import, and inspect multi-slide carousel posts.

carousel generate options:

carousel import options: same as above except no --type / --instructions / --preset-id, plus:

# AI-generated
postnitro carousel generate --context "5 tips for remote work" --type text --wait
postnitro carousel generate --context "https://example.com/post" --type article --wait
 
# Import your own slides
postnitro carousel import --slides '{"slides":[
  {"type":"starting_slide","heading":"Your Title","description":"Intro"},
  {"type":"body_slide","heading":"Key Point","description":"Details"},
  {"type":"ending_slide","heading":"Take Action!","cta_button":"Learn More"}
]}' --wait

Carousel slide rules: the array must contain exactly 1 starting_slide (first), ≥1 body_slide, and exactly 1 ending_slide (last). Every slide needs a heading. Optional per slide: sub_heading, description, image, background_image, cta_button, and layoutType/layoutConfig (see Infographic layout). Run carousel import-template for the authoritative schema.

image

Generate, import, and inspect single-image posts. Mirrors carousel, but produces one image and import takes a single slide object (not an array).

image import options: same as carousel import, but slide input is a single object:

postnitro image generate --context "Announce our new scheduling feature" --wait
postnitro image import --slide '{"heading":"Welcome!","sub_heading":"Subtitle","cta_button":"Learn more"}' --wait

Image slide fields (single object; heading required, all others optional): heading, sub_heading, description, cta_button, image, background_image, plus layoutType/layoutConfig for infographics. Any other field is rejected. Sending an array is rejected — arrays are carousel-only.

schedule

Manage scheduled posts and drafts. Full CRUD is also available via the Schedule API.

schedule create / update options:

A post must have either --design-id or non-empty --post-content. Hashtags are auto-extracted from captions.

postnitro schedule create \
  --status SCHEDULED \
  --scheduled-at "2026-12-31T13:00:00Z" \
  --design-id dsg_abc \
  --selected-accounts '["acct_123"]' \
  --linkedin-post-settings '{"postType":"document","postTitle":"5 remote work tips"}' \
  --post-content '{"common":"New carousel 🚀 #remotework"}'
 
postnitro schedule list --from "2026-01-01" --to "2026-12-31"
postnitro schedule delete sch_123 --yes

generate-and-schedule

One-shot: generate with AI → wait → schedule in a single call. May take 30–180s.

Takes every generate flag (--context required, --type, --instructions, --preset-id, …), plus --post-type CAROUSEL|IMAGE (default CAROUSEL), the AI-image flags, and all the schedule create flags (--status and --scheduled-at required). --file here is the schedule body.

If generation succeeds but scheduling fails, the error returns the designId so you can retry schedule create without regenerating (and re-spending credits).

postnitro generate-and-schedule \
  --context "How AI agents automate content" --type text \
  --status SCHEDULED --scheduled-at "2026-12-31T12:00:00Z" \
  --selected-accounts '["acct_123"]' \
  --linkedin-post-settings '{"postType":"document","postTitle":"How AI agents automate content"}' \
  --post-content '{"common":"New drop 🚀 #ai #automation"}'

import-and-schedule

One-shot: import your own content → wait → schedule in a single call. The import-side counterpart of generate-and-schedule.

Flag note: here --file is the schedule body (like generate-and-schedule), so slide content comes from --slides / --slide / --slides-file, not --file.

postnitro import-and-schedule \
  --slides '{"slides":[ ... ]}' \
  --status SCHEDULED --scheduled-at "2026-12-31T12:00:00Z" \
  --selected-accounts '["acct_123"]' \
  --post-content '{"common":"..."}'

AI image generation

Opt-in: have AI generate images and bake them into the design before rendering. Available on all four create commands and both one-shot commands, for carousels and images alike.

postnitro carousel generate --context "How scheduling saves marketers time" \
  --generate-images --image-context "upbeat and professional, product-focused" \
  --image-placement auto --image-strategy all --wait

• Best-effort. The post still completes if image generation fails or isn’t permitted. With --wait, the result carries an imageGeneration field (the GENERATE_IMAGES step); a FAILED status there explains why (e.g. free plan can’t generate AI images, or the org is over its AI-image quota). Without --wait, the same step appears in status logs.
• Credits. AI images consume the organization’s separate AI-image quota — the post’s slide-based credits are unchanged.
• Adds latency (real images are rendered).

Infographic layout

On either import command, set layoutType: "infographic" on a slide (with a layoutConfig) to render data columns (max 3) instead of an image. Works on both carousel slides and the single image slide.

layoutConfig fields (omitted fields use the defaults shown):

Each columnData entry: id (string), header (string), content (array). Each content item: id (string), icon (string | null), title (string), description (HTML string, e.g. <p dir="ltr">…</p>), titleEnabled (boolean), descriptionEnabled (boolean).

Important: the id fields on columns and items are caller-provided and required — the API stores them as-is and does not auto-generate them. If layoutType is infographic but layoutConfig is missing, the slide falls back to the default layout.

{
  "heading": "Our 2026 Results",
  "layoutType": "infographic",
  "layoutConfig": {
    "hasHeader": true,
    "columnCount": 3,
    "columnDisplay": "grid",
    "displayCounterAs": "counter",
    "columnData": [
      { "id": "col-1", "header": "Growth", "content": [
        { "id": "item-1", "icon": null, "title": "+42%", "description": "<p dir=\"ltr\">Revenue YoY</p>", "titleEnabled": true, "descriptionEnabled": true }
      ]}
    ]
  }
}

Platform settings

Pass per-platform behavior via the --*-post-settings flags when scheduling. Settings are conditionally required based on the platforms among your --selected-accounts. See Platform settings for the full reference.

LinkedIn tip: PDF carousels are normally posted as postType: "document" (which needs a postTitle).

Response types & output

--response-type accepts three values (CLI default is PDF):

Every completed output includes designId, name, size, and editorUrl. PDF/PNG additionally include type, mimeType, and data (the file URLs); DESIGN omits those three.

// PNG output (excerpt)
{
  "designId": "dsg_abc",
  "name": "5 remote work tips",
  "editorUrl": "https://postnitro.ai/app/carousel-maker/pn-xyz/dsg_abc",
  "type": "png",
  "mimeType": "image/png",
  "data": ["https://.../slide_0.png", "https://.../slide_1.png"]
}

Environment variables

* Either --api-key, POSTNITRO_API_KEY, or a saved key (auth set-key) is required.

Errors & exit codes

Every command prints JSON. Failures go to stderr and exit non-zero:

{ "success": false, "error": { "message": "PostNitro API error (422): ...", "statusCode": 422 } }

• Exit 0 — success (JSON on stdout)
• Exit 1 — error (JSON on stderr)

Credits & pricing

The CLI consumes the same credits as the Embed API:

• Content import: ~1 credit per slide
• AI generation: ~2 credits per slide
• AI images: consume the organization’s separate AI-image quota (not post credits); unavailable on the free plan
• Response type (PDF/PNG/DESIGN) does not change credit cost

Command cheat sheet

# Auth
postnitro auth set-key <key> | status | clear
 
# Discovery + defaults
postnitro template list | brand list | preset list | social list
postnitro defaults set --template-id <id> --brand-id <id> --preset-id <id> --response-type PDF
 
# Create (carousel or image; async — use --wait; result has designId + editorUrl)
#   --response-type PDF|PNG|DESIGN   |   optional AI images: --generate-images --image-context "brief" [--image-placement …] [--image-strategy …]
postnitro carousel generate --context "topic|url" --type text|article|x [--instructions "…"] --wait
postnitro carousel import (--slides '{"slides":[…]}' | --file ./slides.json) --wait
postnitro image generate --context "topic|url" --type text|article|x --wait
postnitro image import (--slide '{"heading":"…"}' | --file ./slide.json) --wait
postnitro carousel status <embedPostId>   |  carousel output <embedPostId>     # (also: image status | output)
 
# Brand kits
postnitro brand create (--name --handle --image [--company-detail] | --data '{…}')
postnitro brand update <id> …
 
# Schedule (use designId, not embedPostId; --scheduled-at ≥ 5 min in the future)
postnitro schedule create --status SCHEDULED|DRAFT --scheduled-at "<iso>" --design-id <id> \
  --selected-accounts '["<id>"]' --linkedin-post-settings '{"postType":"document","postTitle":"…"}' \
  --post-content '{"common":"caption"}'
postnitro schedule list --from "<date>" --to "<date>"  |  get <id>  |  update <id> …  |  delete <id> --yes
 
# Social accounts
postnitro social list | get <id> | disconnect <id> --yes
 
# One-shot: create + schedule (both take --post-type + the AI-image flags)
postnitro generate-and-schedule --context "topic" --status SCHEDULED --scheduled-at "<iso>" …
postnitro import-and-schedule --slides '{"slides":[…]}' --status SCHEDULED --scheduled-at "<iso>" …   # or --slide for image
 
# Help
postnitro --help   |   postnitro <command> --help   |   postnitro <command> <subcommand> --help

CLI vs. MCP vs. Embed API vs. Embed SDK

Support

• Email: support@postnitro.ai
• Live Chat: Available on postnitro.ai 
• npm: @postnitro/cli
• GitHub: postnitro/postnitro-agent