How to post to Instagram from Codex CLI
Codex CLI runs the upload from your shell, so an image in the repo becomes an Instagram post without a visit to the dashboard.
How do I post to Instagram from Codex CLI?
Add the planpo.st MCP server to Codex CLI, connect Instagram once in the dashboard, then ask. The first three steps are one-time.
- 1
Create an API key and add planpo.st to Codex CLI
Make a scoped key in planpo.st under Settings. Add a [mcp_servers.planpost] table to ~/.codex/config.toml, or run codex mcp add and answer the prompts. The hosted form reads the token from the environment variable named in bearer_token_env_var, so export PLANPOST_API_KEY in your shell first.
- 2
Confirm the server is connected
Start Codex and run /mcp to check that planpost is connected.
- 3
Connect Instagram
Connect a professional Instagram account in the dashboard under Connections, either through its linked Facebook Page or with Instagram login. When it asks for permissions, leave publishing ticked or posts will fail later.
- 4
Know what the post needs
An Instagram post needs at least one image or video. Captions run to 2,200 characters. Nothing in platformSettings is required; postType picks between a feed post, a Reel and a Story.
- 5
Ask in your terminal
Say what to post and when. Codex CLI finds the Instagram connection, creates the post, and tells you whether it was scheduled or kept as a draft, with the reason.
[mcp_servers.planpost]
url = "https://mcp.planpo.st/mcp"
bearer_token_env_var = "PLANPOST_API_KEY"[mcp_servers.planpost]
command = "npx"
args = ["-y", "planpost-mcp"]
[mcp_servers.planpost.env]
PLANPOST_API_KEY = "pk_live_xxx"Config location: ~/.codex/config.toml, or .codex/config.toml in a trusted project. Replace pk_live_xxx with your own key.
Hosted or local for Codex CLI?
For Codex CLI I would use hosted with bearer_token_env_var, since the config file then holds no secret and can be shared. Use local when you would sooner keep the key in the config file's env table than in your shell profile.
- The hosted form reads the token from an environment variable rather than the file, so export PLANPOST_API_KEY in your shell.
- `codex mcp add` does the same thing interactively if you would rather not edit TOML.
The full walkthrough is on the Codex CLI setup page.
What can Codex CLI do on Instagram?
It can publish single images, carousels of up to 10 items, Reels and Stories, and invite up to 3 collaborators on image and carousel posts. It cannot publish a post without media or make a caption link clickable.
Image or carousel
1 to 10One image is a feed post, two to ten attachments are a carousel. JPEG is what Instagram accepts; PNG files are converted on the way.
Reel
postType "reel" with one video. coverImageTime picks the cover frame, in seconds.
Story
postType "story" with one image or one video.
Collab post
up to 3platformSettings.instagram.collaborators takes Instagram usernames. Works on image and carousel posts.
Instagram needs an image or video on every post, and Codex CLI can take it from disk: it calls upload_media for a presigned URL, PUTs the file there with a shell command, and passes the returned asset into create_post. Files already uploaded come back from list_media, ready to reuse.
Which settings does a Instagram post take?
Instagram reads four settings. Two of them, isReel and isStory, are older flags that postType now sets for you, so in practice an agent sends postType plus the two optional ones.
| Field | Allowed values | If you leave it out | Worth knowing |
|---|---|---|---|
| postType | "post", "reel" or "story" | "post" | Takes precedence over the flags below. A vertical video, or one of 90 seconds or less, is published as a Reel even when this says "post". |
| platformSettings.instagram.isReel | true or false | Set from postType | If it disagrees with an explicit postType it is ignored and the response carries post_type_flag_ignored. |
| platformSettings.instagram.isStory | true or false | Set from postType | Same rule as isReel. Prefer postType "story". |
| platformSettings.instagram.coverImageTime | Seconds into the video | Instagram picks the frame | Reels only. 0 counts as not set. |
| platformSettings.instagram.collaborators | Up to 3 usernames, with or without @ | No collaborators | Single-image and carousel posts only. A fourth name is dropped, and the field is not sent for Reels or Stories. |
| media, platformMedia.instagram | 1 to 10 items. JPEG or PNG images, MP4 or MOV video | None, required | No media saves the post as a draft with media_required. More than 10 fails at publish. |
| platformContent.instagram | Caption, 2,200 characters or fewer | The shared content | A URL in the caption returns a link_not_clickable warning. More than 30 hashtags returns hashtags_over_limit. |
What do I type to post to Instagram from Codex CLI?
Plain requests work. Each example lists the tool calls Codex CLI makes in response.
1. Carousel from something you wrote
You say
Read the pull requests merged this week. Turn it into a 6-slide Instagram carousel in my brand kit and schedule it for Wednesday 18:00.
Tool calls
list_brand_kits()
generate_carousel({ content: "<source text>", platform: "instagram", maxSlides: 6 })
render_carousel({ slides: [...], family: "<id>", brandKitId: "<kit id>" })
get_carousel_render({ id: "<render id>" })
create_post({ content: "<caption>", media: [<6 assets>], connectionIds: ["<instagram id>"], schedule: "wednesday 18:00" })Six slides rendered server-side as images, saved to the media library and scheduled as one carousel. The render tops out at 10 slides, which is also Instagram's cap.
2. A Reel with a chosen cover
You say
The video is at ./out/demo.mp4. Schedule it as an Instagram Reel on Friday 19:00 with the cover taken 3 seconds in.
Tool calls
upload_media({ filename: "demo.mp4", contentType: "video/mp4", size: <bytes> })
PUT <file> to the returned URL (shell)
create_post({ content: "<caption>", postType: "reel", platformSettings: { instagram: { coverImageTime: 3 } }, media: [<video>], connectionIds: ["<instagram id>"], schedule: "friday 19:00" })One scheduled Reel. The video has to be MP4 or MOV; anything else is refused with the format named.
3. A collab post
You say
The image is at ./out/card.jpg. Post it to Instagram tomorrow 11:00 as a collab with @partnerstudio, caption about the joint launch.
Tool calls
upload_media({ filename: "cover.jpg", contentType: "image/jpeg", size: <bytes> })
PUT <file> to the returned URL (shell)
create_post({ content: "<caption>", platformSettings: { instagram: { collaborators: ["partnerstudio"] } }, media: [<image>], connectionIds: ["<instagram id>"], schedule: "tomorrow 11:00" })An image post that invites the other account as a collaborator. They still have to accept the invite in Instagram before it shows on their profile.
What stops a Instagram post from Codex CLI?
The tag on a card is the code that comes back in the tool result.
No media, no post
media_requiredA text-only post that targets Instagram is saved as a draft. If the same post also goes to X or LinkedIn, give Instagram its own attachments in platformMedia.instagram.
Image rules
JPEG, at least 320 pixels wide, 8 MB or smaller, aspect ratio between 4:5 and 1.91:1. PNG is converted to JPEG. GIF and WebP are refused.
10 items per carousel
Eleven attachments fail at publish with the count in the error. Trim the set before scheduling.
Short or vertical video becomes a Reel
A portrait video, or any video of 90 seconds or less, is published as a Reel whatever the post type says. Instagram does not take those as feed video.
Caption links do not work
link_not_clickableInstagram shows the URL as plain text. The create call warns about it and still schedules the post.
30 hashtags
hashtags_over_limitPast 30 the response carries a warning with the count.
The token comes from your shell
Codex CLIThe hosted config names an environment variable, it does not hold the key. If PLANPOST_API_KEY is not exported in the shell that starts Codex, every call fails with an authorization error.
Can Codex CLI tell me what a Instagram post earned?
Partly. A caption link on Instagram is not clickable, so a tracked link in a caption has nothing to click and the post earns no attributed revenue from it. The clickable places are the bio link and Story link stickers, and the Instagram guide covers how those are tracked. get_revenue_overview returns totals either way, and for shops selling through Instagram the other end is usually Shopify.
Codex CLI and Instagram: questions people ask
- Which image formats does it accept for Instagram?
- JPEG, and PNG which is converted to JPEG before upload. GIF and WebP are refused. Images must be at least 320 pixels wide, 8 MB or less, and between 4:5 and 1.91:1.
- Why did my video post as a Reel?
- Because it was vertical or no longer than 90 seconds. Instagram accepts those as Reels only, so the publisher routes them there.
- What happens when Codex CLI sends a Instagram post that breaks a rule?
- It is told at once. The usual case on Instagram is a post with no image or video: the post is kept as a draft and the tool result carries media_required plus the fix, which Codex CLI applies with update_post.
- Where does the config go?
- In ~/.codex/config.toml, or .codex/config.toml in a trusted project. It is TOML, not JSON, which trips people who paste a snippet from another client. Once it loads, the Instagram tools are available in every session.
- Does the key have to be in the file?
- Not for the hosted server. bearer_token_env_var names a variable and Codex reads the key from your environment, so the file can be shared. The local form puts it under [mcp_servers.planpost.env]. Neither choice changes what you can post to Instagram.
Keep going
Instagram from other agents
Other networks from Codex CLI