# DunSocial CLI: schedule and publish social posts from the terminal

> `dunsocial` is the DunSocial command-line interface. Install it with `npm install -g dunsocial` and the `dun` command schedules, publishes and manages posts from your terminal, a CI job or a coding agent. Node 20 or newer.

## What it is

A thin client over the DunSocial REST API. It holds no state of its own beyond a token: every command drives the same workspace, the same connected accounts and the same calendar as the web app, so a post scheduled from a shell script appears in the app immediately.

It is included in the plan, at no extra cost. Posts created from the CLI are tagged with a CLI source in the app, so you can always see what a script did.

- Package: `dunsocial` on npm, https://www.npmjs.com/package/dunsocial
- Commands: `dun` and `dunsocial`, the same program under two names.
- Requires: Node.js 20 or newer, and npm.
- Runs on: macOS, Linux and Windows.
- Config file: `~/.config/dunsocial/config.json`, mode 0600. Environment variables take precedence over it.

## What you can do with it

- Schedule, publish, reschedule, cancel and delete posts from the terminal
- Works on X, LinkedIn, Instagram, Threads, Bluesky, Reddit, Pinterest and YouTube, the same accounts the app posts to
- Device-code browser login for humans, scoped access tokens for CI and agents
- `--json` on every command, with a stable success and error envelope
- Distinct exit codes for usage, auth, permission, validation, not-found, rate-limit and network failures
- Drafts, media uploads and AI memory, all scriptable
- Multiple workspaces, switchable per command with `--workspace`
- Agent skill files for Claude Code and Codex, installed with one command
- Posts created from the CLI are tagged with a CLI source in the app

## Quickstart

1. **Install it.** Node 20 or newer. The package installs two bins, `dun` and `dunsocial`; they are the same program.

   ```bash
   npm install -g dunsocial
   dun --version
   ```

2. **Sign in.** A browser opens so you can approve this machine. The token is written to your config file, mode 0600. On a headless box, add `--no-browser`.

   ```bash
   dun auth login
   dun auth status
   ```

3. **Pick a workspace and find an account.** Posts are addressed by account id, not by @handle, so that two accounts with the same handle on different networks stay unambiguous.

   ```bash
   dun workspace use my-team
   dun accounts list
   ```

4. **Post.** Schedule with a relative offset (`--in 2h`) or an exact instant (`--at 2026-08-01T09:00:00Z`). Drop the timing flags and use `publish` to send it now.

   ```bash
   dun posts schedule \
     --text "v2.1 is live" \
     --accounts acc_x1,acc_li3 \
     --in 1h
   ```

## Commands

| Group | Commands | What it is for |
| --- | --- | --- |
| Auth | login, logout, whoami, status | Device-code browser login, or a token for CI. |
| Workspaces | list, use, current | Pick the workspace every later command runs against. |
| Accounts | list | The connected social accounts, and the ids you post with. |
| Posts | list, get, schedule, publish, reschedule, cancel, delete, x-cap | Schedule with an exact time or a relative one. Publish now. |
| Drafts | list, get, create, update, delete | Park an idea until it is ready to go out. |
| Media | list, get, upload, delete | Upload an image or video and attach it to a post. |
| Memory | collections list, collections create, list, save, search, delete | Brand facts and tone, with semantic search over them. |
| Skills | install <agent\|all>, list, path | Drop a DunSocial skill file into Claude, Cursor, OpenCode, Copilot, and other agents. |

Every group prints its own help, for example `dun posts --help`. Global flags: `--json`, `--workspace <id>`, `--api-url <url>`, `--token <token>`, `--debug`, `--quiet`, `--yes`, `--help`, `--version`.

## Authentication

Two ways in, for two kinds of caller.

- **Device login, for humans.** `dun auth login` opens a browser so you can approve the machine. Add `--no-browser` on a headless box. The token is written to the config file.
- **Access tokens, for CI and agents.** Create one in the app under Settings, CLI. A token is scoped to a set of permissions, bound to a single workspace, and stored as a hash, so it can be revoked on its own without disturbing any other token. Set it as `DUN_TOKEN` and the CLI never prompts.

## Output contract

Every command accepts `--json`, and it is the default whenever stdout is not a terminal, which is what makes the CLI safe to call from a script without remembering the flag. Success and failure are the same document with a different `ok`:

```json
{
  "ok": true,
  "data": { … }
}
```

```json
{
  "ok": false,
  "error": {
    "code": "validation_failed",
    "message": "…",
    "details": { … }
  }
}
```

Debug and progress output goes to stderr only, so stdout is always clean enough to pipe.

## Exit codes

| Code | Meaning |
| --- | --- |
| 0 | Success |
| 1 | Usage error |
| 2 | Not authenticated |
| 3 | Forbidden |
| 4 | Validation failed |
| 5 | Not found |
| 6 | Rate limited |
| 7 | Network error |

## Environment variables

| Variable | Meaning |
| --- | --- |
| `DUN_TOKEN` | Access token. Set this in CI instead of logging in. |
| `DUN_WORKSPACE_ID` | The workspace to act on. |
| `DUN_API_URL` | API base. Defaults to https://api.dunsocial.com. |
| `DUN_JSON` | Force machine-readable output. |
| `DUN_DEBUG` | Log HTTP method, path and status to stderr. |
| `DUN_CONFIG` | Point at a different config file. |

## Posting from CI

Announce a release from the same workflow that ships it:

```yaml
name: Announce release
on:
  release:
    types: [published]

jobs:
  post:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Schedule the announcement
        env:
          DUN_TOKEN: ${{ secrets.DUN_TOKEN }}
          DUN_WORKSPACE_ID: ${{ secrets.DUN_WORKSPACE_ID }}
        run: |
          npx --yes dunsocial posts schedule \
            --text "Shipped ${{ github.event.release.tag_name }}" \
            --accounts ${{ secrets.DUN_X_ACCOUNT_ID }} \
            --in 5m \
            --json
```

## Agent skills

`dun skill install <agent|all>` writes a DunSocial skill file into coding agents (Claude, Codex, Cursor, Pi, OpenCode, Copilot, Windsurf, Gemini, Amp, Grok, Continue, Antigravity, and the shared `~/.agents/skills` path). `dun skill list` shows targets; `dun skill path` prints the bundled source.

## CLI or MCP

Use the CLI where you already have a shell: your terminal, a CI job, or a coding agent working in your repo. Use MCP where the assistant is remote and has no terminal, such as Claude or ChatGPT in the browser. Both drive the same workspace and the same connected accounts.

The MCP server is documented at https://www.dunsocial.com/mcp (Markdown: https://www.dunsocial.com/mcp.md).

## Pricing

The CLI is included in the plan, at no extra cost.

- One plan: $20 per month, or $192 per year (save 20%).
- Every feature is included, and scheduled posts are unlimited.
- Base plan includes 1 seat. Additional team seats: $8 per month, or $77 per year, each.
- 14-day free trial, with every feature unlocked.

## About this document

This is the Markdown representation of https://www.dunsocial.com/cli. The HTML version of the same page is at the same URL. You can also request Markdown from any page by sending `Accept: text/markdown`.

Machine-readable summary of the whole site: https://www.dunsocial.com/llms.txt

## Company

- Product: DunSocial, https://www.dunsocial.com
- Legal entity: THISUX PRIVATE LIMITED, Chennai, Tamil Nadu, India
- Support: support@dunsocial.com
- Open the app: https://app.dunsocial.com/login