> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autoposting.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Commands

> Complete command reference for the Autoposting CLI — 75 commands across 14 domains.

## Posts

### `ap posts create`

Create one or more posts — with media, per-platform overrides, per-account targeting, scheduling, threads, or in bulk from a file.

<CodeGroup>
  ```bash Basic theme={null}
  ap posts create --brand my-brand --text "Hello world!" --platforms x,linkedin
  ```

  ```bash Thread theme={null}
  ap posts create --brand my-brand --text "Tweet 1" --thread "Tweet 2" "Tweet 3" --platforms x
  ```

  ```bash Media + alt text theme={null}
  ap posts create --brand my-brand --text "Launch day" --platforms x,instagram \
    --media ./hero.png ./demo.mp4 --alt-text "Product hero" "Demo clip"
  ```

  ```bash Schedule theme={null}
  ap posts create --brand my-brand --text "Going live soon" --platforms x \
    --at 2026-07-01T09:00:00Z
  ```

  ```bash Per-account theme={null}
  ap posts create --brand my-brand --text "From the main account" --platforms x \
    --account x=@myhandle
  ```

  ```bash Bulk theme={null}
  ap posts create --from ./posts.csv
  ```

  ```bash Dry run theme={null}
  ap posts create --brand my-brand --text "Preview only" --platforms x --dry-run
  ```
</CodeGroup>

**Core flags**

| Flag                      | Description                                                                                        |
| ------------------------- | -------------------------------------------------------------------------------------------------- |
| `--brand <slug>`          | Brand slug. Falls back to the saved context (`ap config set-context`); required if neither is set. |
| `--text <text>`           | Post text content (required unless `--from`)                                                       |
| `--platforms <list>`      | Comma-separated (required unless `--from`): `x,linkedin,instagram,threads,youtube`                 |
| `--at <iso>`              | ISO 8601 datetime to schedule at create. A past time is rejected.                                  |
| `--thread <text...>`      | Extra posts appended after `--text` to form a thread (X/Threads, max 25)                           |
| `--from <file>`           | Create posts in bulk from a CSV or JSON file (one post per row)                                    |
| `--dry-run` / `--preview` | Print the resolved request body without uploading media or creating the post                       |

**Media & per-platform**

| Flag                          | Description                                                                                  |
| ----------------------------- | -------------------------------------------------------------------------------------------- |
| `--media <path...>`           | Media files to attach (max 10)                                                               |
| `--alt-text <text...>`        | Alt text for `--media` files, aligned by index                                               |
| `--platform-media <pairs...>` | Per-platform media, e.g. `instagram=photo.jpg x=banner.png`                                  |
| `--platform-text <pairs...>`  | Per-platform text, e.g. `x=Hello linkedin=World`                                             |
| `--account <p=handle\|id...>` | Target a specific account per platform — see [Per-account targeting](#per-account-targeting) |

**Platform-specific options**

<CodeGroup>
  ```bash YouTube theme={null}
  --yt-title <t>             # Video title
  --yt-description <d>       # Video description
  --yt-tags <list>           # Comma-separated tags
  --yt-privacy <v>           # public | unlisted | private
  --yt-category <id>         # Category ID
  --yt-made-for-kids         # Mark as made for kids
  ```

  ```bash Instagram theme={null}
  --ig-reel                  # Post as a Reel
  --ig-share-to-feed         # Share Reel to feed
  --ig-cover-url <url>       # Reel cover image URL
  --ig-thumb-offset-ms <n>   # Reel thumbnail offset (ms)
  --ig-collaborators <list>  # Collaborator handles (comma-separated)
  ```

  ```bash Threads theme={null}
  --threads-reply-to <id>      # Threads post ID to reply to
  --threads-reply-control <v>  # everyone | accounts_you_follow | mentioned_only
  ```
</CodeGroup>

#### Per-account targeting

`--account <platform>=<handle|id>` selects which connected account to post from when a brand has more than one on a platform. Repeat it per platform.

* `--account x=@handle` — match by handle (case-insensitive, leading `@` optional) or platform user ID.
* `--account linkedin=all` (or `=*`) — fan out to **every** connected account on that platform. A fan-out over 5 accounts asks for confirmation on an interactive terminal.
* On a TTY with 2+ accounts and no `--account`, the CLI shows an interactive checkbox picker.
* Non-interactive (piped/CI) with 2+ accounts and no `--account` errors out and lists the accounts — pass `--account` to choose.
* Save a default per brand+platform with [`ap brands set-default-account`](#ap-brands-set-default-account) to skip the picker.

***

### `ap posts list`

```bash theme={null}
ap posts list [--brand <slug>] [--status <status>] [--limit <n>] [--page <n>]
```

| Flag                | Description                                          |
| ------------------- | ---------------------------------------------------- |
| `--brand <slug>`    | Filter by brand slug (defaults to the saved context) |
| `--status <status>` | `draft`, `scheduled`, `published`, or `failed`       |
| `--limit <n>`       | Max results per page (default 20)                    |
| `--page <n>`        | Page number (default 1)                              |

### `ap posts get`

```bash theme={null}
ap posts get <post-id>
```

### `ap posts update`

```bash theme={null}
ap posts update <post-id> --text "Updated copy"
```

### `ap posts publish`

Publish a draft post immediately.

```bash theme={null}
ap posts publish <post-id>
```

### `ap posts schedule`

Schedule a post for a specific time, or unschedule it back to draft with `--cancel`.

```bash theme={null}
ap posts schedule <post-id> --at "2026-07-01T10:00:00Z"
ap posts schedule <post-id> --cancel
```

| Flag         | Description                                                               |
| ------------ | ------------------------------------------------------------------------- |
| `--at <iso>` | ISO 8601 datetime to schedule (must be in the future)                     |
| `--cancel`   | Unschedule the post (return it to draft). Mutually exclusive with `--at`. |

### `ap posts retry`

Retry a failed post on specific or all platforms.

```bash theme={null}
ap posts retry <post-id> [--platforms x,linkedin]
```

### `ap posts delete`

Requires `--force` to confirm.

```bash theme={null}
ap posts delete <post-id> --force
```

### `ap posts rewrite`

AI-rewrite a post for better engagement.

```bash theme={null}
ap posts rewrite <post-id>
```

### `ap posts score`

Get an AI score and feedback for a post.

```bash theme={null}
ap posts score <post-id>
```

***

## Config

CLI defaults are stored in `~/.config/autoposting/config.json` (sibling to credentials, `0600` permissions).

### `ap config set-context`

Set the default brand applied whenever `--brand` is omitted.

```bash theme={null}
ap config set-context --brand my-brand
```

### `ap config get-context`

```bash theme={null}
ap config get-context
```

### `ap config unset-context`

```bash theme={null}
ap config unset-context
```

<Note>
  **Brand resolution:** an explicit `--brand` flag wins, then the saved context, then the command errors. Set a context once to drop `--brand` from every command.
</Note>

***

## Brands

### `ap brands create`

```bash theme={null}
ap brands create --name "My Brand" --timezone "America/New_York"
```

### `ap brands list`

```bash theme={null}
ap brands list [--json]
```

### `ap brands get`

```bash theme={null}
ap brands get <slug>
```

### `ap brands update`

```bash theme={null}
ap brands update <slug> --name "New Name"
```

### `ap brands delete`

```bash theme={null}
ap brands delete <slug>
```

<Warning>
  Brand deletion also removes all associated platform tokens. Posts are not deleted.
</Warning>

### `ap brands auth-status`

Check which platforms are connected for a brand.

```bash theme={null}
ap brands auth-status <slug>
```

### `ap brands set-default-account`

Save the default target account(s) for a brand, used when `posts create --account` is omitted. Local-only (stored in `config.json`).

```bash theme={null}
ap brands set-default-account my-brand x=@myhandle linkedin=all
```

### `ap brands get-default-account`

```bash theme={null}
ap brands get-default-account my-brand
```

### `ap brands clear-default-account`

Remove all saved default accounts for a brand.

```bash theme={null}
ap brands clear-default-account my-brand
```

***

## Agents

### `ap agents create`

```bash theme={null}
ap agents create --name "Daily News" --type publish --frequency daily --time "09:00"
```

### `ap agents list`

```bash theme={null}
ap agents list [--json]
```

### `ap agents get`

```bash theme={null}
ap agents get <agent-id>
```

### `ap agents update`

```bash theme={null}
ap agents update <agent-id> --name "Weekly Digest"
```

### `ap agents run`

Trigger an immediate agent run.

```bash theme={null}
ap agents run <agent-id>
```

### `ap agents toggle`

Enable or disable an agent.

```bash theme={null}
ap agents toggle <agent-id>
```

### `ap agents runs`

View run history for an agent.

```bash theme={null}
ap agents runs <agent-id>
```

### `ap agents delete`

```bash theme={null}
ap agents delete <agent-id>
```

***

## Knowledge Base

### `ap kb create`

```bash theme={null}
ap kb create --name "Product Docs"
```

### `ap kb list`

```bash theme={null}
ap kb list [--json]
```

### `ap kb get`

```bash theme={null}
ap kb get <kb-id>
```

### `ap kb search`

Search knowledge base content.

```bash theme={null}
ap kb search <kb-id> --query "pricing"
```

### `ap kb ingest`

Ingest a URL into a knowledge base.

```bash theme={null}
ap kb ingest <kb-id> --url "https://docs.example.com"
```

### `ap kb docs`

List documents in a knowledge base.

```bash theme={null}
ap kb docs <kb-id>
```

### `ap kb delete`

```bash theme={null}
ap kb delete <kb-id>
```

***

## Ideas

### `ap ideas generate`

AI-generate content ideas from a topic.

```bash theme={null}
ap ideas generate --topic "product launch" --count 10
```

### `ap ideas list`

```bash theme={null}
ap ideas list [--json]
```

### `ap ideas enrich`

Enrich an idea into platform-ready drafts (async — returns a job ID).

```bash theme={null}
ap ideas enrich --title "<title>" --hook "<hook>" --angle "<angle>" --platforms twitter,linkedin [--kb <id>]
```

| Flag          | Description                                                                     |
| ------------- | ------------------------------------------------------------------------------- |
| `--title`     | Idea title (required)                                                           |
| `--hook`      | Idea hook (required)                                                            |
| `--angle`     | Idea angle (required)                                                           |
| `--platforms` | Comma-separated, max 5: `twitter,linkedin,instagram,youtube,threads` (required) |
| `--kb`        | Knowledge base ID for extra context (optional)                                  |

### `ap ideas delete`

```bash theme={null}
ap ideas delete <idea-id>
```

***

## Clips

### `ap clips upload`

Upload a local video file as a clip. The brand resolves automatically when your
workspace has a single brand; pass `--brand <id>` to choose when you have more
than one. Use `--name` to override the clip title (defaults to the filename).

```bash theme={null}
ap clips upload ./video.mp4 [--brand <id>] [--name "My Clip"]
```

### `ap clips import`

Import a video from a URL for AI clipping.

```bash theme={null}
ap clips import --url "https://youtube.com/watch?v=..."
```

### `ap clips list`

```bash theme={null}
ap clips list [--json]
```

### `ap clips get`

```bash theme={null}
ap clips get <clip-id>
```

### `ap clips render`

Render a clip for publishing.

```bash theme={null}
ap clips render <clip-id>
```

### `ap clips delete`

```bash theme={null}
ap clips delete <clip-id>
```

***

## Carousels

### `ap carousels generate`

AI-generate a carousel from a topic.

```bash theme={null}
ap carousels generate --topic "5 Growth Tips" --brand my-brand --slides 5
```

### `ap carousels create`

Create a carousel manually.

```bash theme={null}
ap carousels create --brand my-brand --title "My Carousel"
```

### `ap carousels list`

```bash theme={null}
ap carousels list [--json]
```

### `ap carousels get`

```bash theme={null}
ap carousels get <carousel-id>
```

### `ap carousels draft`

Convert a carousel into a post draft.

```bash theme={null}
ap carousels draft <carousel-id>
```

### `ap carousels delete`

```bash theme={null}
ap carousels delete <carousel-id>
```

***

## Webhooks

### `ap webhooks create`

```bash theme={null}
ap webhooks create --url "https://api.example.com/hook" --events "post.published,post.failed"
```

### `ap webhooks list`

```bash theme={null}
ap webhooks list [--json]
```

### `ap webhooks get`

```bash theme={null}
ap webhooks get <webhook-id>
```

### `ap webhooks update`

```bash theme={null}
ap webhooks update <webhook-id> --url "https://new-url.com/hook"
```

### `ap webhooks test`

Send a test event to a webhook endpoint.

```bash theme={null}
ap webhooks test <webhook-id>
```

### `ap webhooks delete`

```bash theme={null}
ap webhooks delete <webhook-id>
```

***

## Billing & Usage

### `ap billing status`

Show current plan and subscription details.

```bash theme={null}
ap billing status
```

### `ap billing credits`

Show AI credit balance.

```bash theme={null}
ap billing credits
```

### `ap usage summary`

Show publishing statistics.

```bash theme={null}
ap usage summary
```

***

## Workspaces

### `ap workspaces list`

```bash theme={null}
ap workspaces list
```

### `ap workspaces switch`

Switch to a different workspace (session auth only).

```bash theme={null}
ap workspaces switch <workspace-id>
```

***

## Auth

### `ap auth login`

Log in via browser device-code flow, or store an API key directly.

```bash theme={null}
ap auth login
ap auth login --api-key sk-social-your-key --profile work
```

| Flag               | Description                                       |
| ------------------ | ------------------------------------------------- |
| `--api-key <key>`  | Store a key directly (skips the device-code flow) |
| `--profile <name>` | Profile to save under (default `default`)         |
| `--base-url <url>` | API base URL (overrides `AUTOPOSTING_BASE_URL`)   |

### `ap auth logout`

Remove the active profile, or all profiles with `--all`.

```bash theme={null}
ap auth logout [--all]
```

### `ap auth switch`

Switch the active profile.

```bash theme={null}
ap auth switch <profile>
```

### `ap auth whoami` / `ap auth status`

Show the current auth method and identity (`status` is an alias).

```bash theme={null}
ap auth whoami
```

***

## Utility

### `ap doctor`

Health check — verifies CLI version, Node.js, authentication, and API connectivity.

```bash theme={null}
ap doctor
```

### `ap whoami`

Show the current auth source and workspace.

```bash theme={null}
ap whoami
```

### `ap open`

Open a resource in your browser.

```bash theme={null}
ap open posts
ap open brands
```

### `ap update`

Check for CLI updates.

```bash theme={null}
ap update
```

### `ap completion`

Generate shell completions.

```bash theme={null}
ap completion zsh >> ~/.zshrc
ap completion bash >> ~/.bashrc
ap completion fish > ~/.config/fish/completions/ap.fish
```

### `ap mcp`

Start the built-in MCP server for AI agents.

```bash theme={null}
ap mcp
```

See [MCP Server](/mcp/overview) for full details.

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/cli/installation">
    Install and configure the CLI.
  </Card>

  <Card title="MCP Tools" icon="robot" href="/mcp/tools">
    Same operations as MCP tool calls for AI agents.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Underlying REST endpoints.
  </Card>

  <Card title="TypeScript SDK" icon="brackets-curly" href="/sdks/typescript">
    Programmatic API access in Node.js.
  </Card>
</CardGroup>