> **Shapeless documentation index**
> Fetch https://shapelessai.com/llms.txt to discover every page before exploring further.
> Every page also answers Markdown: append `.md` to its path, or send `Accept: text/markdown`.

# CLI

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

*Verified 2026-09-14. Source: https://shapelessai.com/docs/cli*

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](/docs/api), so
there is one implementation and one scope policy underneath.

## Install

```bash
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](https://github.com/FirstClassTree/shapelessai).

## Sign in

```bash
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

```bash
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](/docs/posts#the-free-day).

## Work the queue

```bash
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

```bash
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](/docs/jobs).

## Actors, Brand Memory, assets

```bash
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](/docs/brand-memory).

## The local MCP server

```bash
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](/docs/mcp).