PostNitro CLI

The PostNitro CLI creates on-brand social media posts — multi-slide carousels, single images, and short videos — 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.

video

Generate, import, and inspect video posts. Slides are scenes, so video import takes the same slide array as carousel import — see Video posts for the API-level rules.

Video-only options (on top of the carousel options):

# AI-generated, rendered to MP4
postnitro video generate --context "3 habits that make remote teams faster" \
  --response-type MP4 --video-duration 30 --wait
 
# Your own scenes, with an audio track
AUDIO=$(postnitro audio list | jq -r '.audios[0].id')
postnitro video import --file ./scenes.json \
  --response-type MP4 --video-duration 30 --audio-id "$AUDIO" --wait
 
# Design only — no render; finish it in the video maker via editorUrl
postnitro video generate --context "..." --wait

Rendering a video takes longer than a carousel — typically 15–45s with --wait and MP4, and longer for designs with animations or GIFs (which use the enhanced renderer). A saved PDF/PNG default doesn’t apply to a video: it’s treated as DESIGN and noted in warnings rather than failing the call. The duration and audio are reused automatically when the video is scheduled as a reel.

audio

List and delete the workspace’s audio tracks — the source of the --audio-id used by video, and of postSettings.audioId when scheduling a reel. See the Audio API.

postnitro audio list
postnitro audio delete aud_123 --yes

audio list returns { id, name, url, duration, artistName, source, createdAt } per track. Pass id as --audio-id; url is for previewing only. A track’s duration is independent of --video-duration — a longer track is cut off at the video’s length.

Uploading is done in the PostNitro app. The CLI (like the API) lists and deletes audio but cannot upload it. An empty list comes back with a note saying so — create the video without --audio-id in the meantime.

audio delete is refused while a scheduled post still references the track. Videos already rendered to MP4 keep their audio, since the track is baked into the file.

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.

--post-settings may be omitted for a reel: the API fills the duration and audio from the settings the attached design was generated with, then falls back to 30 seconds with no audio. videoDuration must be at least 5 and under 60, and audioId must be an audio ID in your workspace.

schedule list accepts --accounts <id,id> (comma-separated IDs from social list) to narrow the range to specific accounts. It filters posts, not the accounts within them: a post targeting LinkedIn and Instagram is returned when you filter by either, and it still reports both. Unknown IDs match nothing rather than erroring.

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 list --from "2026-01-01" --to "2026-12-31" --accounts "acct_123,acct_456"
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|VIDEO (default CAROUSEL; a video also takes --video-duration/--audio-id), 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 six create commands and both one-shot commands — carousels, images, and videos 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 four values (CLI default is PDF, except on video, which defaults to DESIGN):

MP4 and the other rendered formats don’t mix: a video accepts only MP4 or DESIGN, and MP4 is rejected for carousels and images. MP4 also can’t be stored with defaults set, since it would break every carousel and image call — pass it per call.

Every completed output includes designId, name, size, and editorUrl. PDF/PNG/MP4 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, image, or video; async — use --wait; result has designId + editorUrl)
#   --response-type PDF|PNG|DESIGN (MP4 for video)   |   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 video generate --context "topic|url" --response-type MP4 --video-duration 30 [--audio-id <id>] --wait
postnitro video import (--slides '{"slides":[…]}' | --file ./scenes.json) --response-type MP4 --video-duration 30 --wait
postnitro carousel status <embedPostId>   |  carousel output <embedPostId>     # (also: image | video status | output)
 
# Audio for videos & reels (upload happens in the app)
postnitro audio list   |   audio delete <audioId> --yes
 
# 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>" [--accounts "<id>,<id>"]  |  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 CAROUSEL|IMAGE|VIDEO + 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