ShapelessAI← Back
Interfaces

CLI

The `shapeless` command: install, sign in, and drive the same account from a terminal or a cron job.

Verified
View as Markdown

One npm package, two faces: the shapeless command, and an MCP server (shapeless mcp) exposing the same operations as tools. Both are built on the routes in the API reference, so there is one implementation and one scope policy underneath.

Install

npx shapelessai --help      # one-off
npm i -g shapelessai        # keeps `shapeless` on your PATH

Node 20 or newer. Source and issues: github.com/FirstClassTree/shapelessai.

Sign in

shapeless login                    # paste a key from /studio/api-keys; stored 0600
export SHAPELESS_API_KEY=slk_...   # beats the stored key - the shape for CI

Config lives in ~/.config/shapeless/config.json. SHAPELESS_BASE_URL overrides the API host (default https://shapelessai.com). shapeless logout forgets the local copy; revoke the key itself in the studio.

Every command takes --json to print the raw API response, and --help.

Post

shapeless connections                      # the connected accounts and their ids
shapeless platforms                        # limits and rules, no key needed

shapeless posts create --to <connectionId> --text "Shipped the thing."
shapeless posts create --to <connectionId> --text "..." --at 2026-09-22T07:00:00Z
shapeless posts create --to <connectionId> --text "..." --queue
shapeless posts create --to <connectionId> --text "..." \
  --media workspace-assets/<account>/carousel.pdf --title "Ten lessons" \
  --first-comment "Full write-up: https://..."
shapeless posts create --to <connectionId> --text "..." --settings '{"subreddit":"startups","title":"..."}'
shapeless posts create --to <youtubeConnectionId> --text "..." --media <clip.mp4 key> \
  --title "The video title" --settings '{"privacyStatus":"unlisted"}'

Flags map one-to-one onto the POST /api/posts body: --to is connectionId, --text is postText, --at is scheduledAt, --queue is queue, --media is a comma-separated mediaKeys, --title is documentTitle (YouTube needs one), --settings is settings, and --first-comment is firstComment. --at and --queue are exclusive. Needs a key with publish.

On the Free plan the sixth post for one UTC day answers 402 free_daily_cap naming the day that is full - see Posts.

Work the queue

shapeless posts list --status proposed
shapeless posts list --status published   # LIFT: each post against its channel's median
shapeless posts show <id>                 # what it was made from, and how it did
shapeless posts approve <id> <id> <id>    # proposed -> scheduled  [publish]
shapeless posts dismiss <id>
shapeless posts publish <id>              # out, now  [publish]
shapeless posts mark-posted <id> --url https://...

A published post carries metrics: the latest reading, its standing at 24h and 7d, and lift - its score over the median of the same channel's last 90 days. Lift stays blank until at least five scored posts stand behind that median, because a two-post median invents findings.

Jobs

shapeless jobs create draft three posts about our beta launch
shapeless jobs create plan this week --label "Weekly plan" --budget 2.50 --watch
shapeless jobs list                       # 200 newest; prints a cursor if older jobs exist
shapeless jobs list --before <cursor>
shapeless jobs show <id>
shapeless jobs tail <id>
shapeless jobs continue <id> keep going, but make the second post shorter --watch
shapeless jobs stop <id>

shapeless jobs create does this thumbnail work? --attach ./thumb.png --attach ./notes.md
shapeless jobs continue <id> and this one --media-key workspace-assets/<account>/logo.png

See Jobs.

Actors, Brand Memory, assets

shapeless characters list
shapeless characters voice maya --describe "warm documentary narrator, mid-40s, slight gravel"   # SPENDS CREDIT
shapeless characters voice maya --clone workspace-assets/<account>/take.weba --consent

shapeless brain ls
shapeless brain get positioning.md
shapeless brain put voice.md --file ./voice.md
shapeless brain import ./pitch-deck.pdf
shapeless brain export --out brain.zip

shapeless agents list
shapeless agents wake <id>                # [publish]

shapeless assets list
shapeless assets upload ./logo.png

See Brand Memory.

The local MCP server

shapeless mcp

Speaks MCP on stdio using the key from shapeless login, and adds the tools that read your disk - assets_upload, brain_import, and files on a job message - which the hosted server cannot have. Most people want the hosted server instead: see MCP server.