# DunSocial CLI for social media management and scheduling > `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 Social media management using the CLI runs through a thin client over the DunSocial REST API. It holds no state of its own beyond a token: every command drives the same workspace, connected accounts and calendar as the web app. 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 , 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 `, `--api-url `, `--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 ` 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. ## Frequently asked questions ### Can I manage social media using a CLI? Yes. The DunSocial CLI can create drafts, schedule and publish posts, manage media and inspect connected accounts from a terminal, script, CI job or coding agent. It uses the same workspace and calendar as the web app. ### What do I need to install the DunSocial CLI? Install dunsocial globally from npm on macOS, Linux or Windows. The package requires Node.js 20 or newer and exposes both dun and dunsocial as command names. ### How do I sign in from my own computer? Run dun auth login. The CLI opens a browser for device approval and stores the resulting configuration locally with restricted file permissions. Use --no-browser when you need to open the approval URL manually. ### How should a CI job or local agent authenticate? Create a Personal Access Token in DunSocial settings, bind it to the intended workspace and grant only the scopes the automation needs. Store it as DUN_TOKEN and the CLI can run without an interactive login. ### Can scripts rely on machine-readable output? Yes. Every command supports JSON output, stdout stays clean for piping, and errors use stable exit codes for usage, authentication, permissions, validation, missing resources, rate limits and network failures. ### Will CLI-created posts appear in the web app? Yes. The CLI is a thin client over the same DunSocial workspace, connected accounts and calendar. Posts created from it are tagged with a CLI source so your team can see where the action came from. ### Should I use the CLI or MCP? Use the CLI for terminals, shell scripts, local coding agents and CI pipelines. Use MCP when a remote assistant such as Claude, ChatGPT or Cursor should discover and call DunSocial tools conversationally. Both work with the same workspace. ### Can the CLI install a DunSocial skill for my coding agent? Yes. dun skill list shows supported agents, and dun skill install can add the bundled DunSocial skill for Claude, Codex, Cursor, OpenCode, Copilot, Windsurf, Gemini and other agent environments. ## 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