publishport

Files (1)

• SKILL.md

SKILL.md (first lines)

# Publishing with PublishPort

PublishPort runs publishing commands **on the user's own machine, inside their own logged-in
browser**. No platform API keys, no cloud account impersonation — every action comes from the
user's real session, which is why platforms with no public write API (Xiaohongshu, Douyin,
Zhihu, WeChat…) can be published to at all.

Two rules matter more than everything else below:

- **Never guess a flag.** Ask the CLI for its schema; it is the only accurate source.
- **Never publish twice.** A command that errors may still have posted. Check, then retry.

Throughout this file, `publishport` means the official CLI. Run it as
`npx -y publishport@latest <command>`, or install it once with `npm install -g publishport`.

## 0. Setup

If you were pointed at this file to set PublishPort up, do these steps in order. If
`publishport status` already reports a credential, skip step 2.

1. **Install this skill**, so future sessions know how to publish without being sent here again:

   ```bash
   npx -y skills add https://www.publishport.app/skill.md -g -y
   ```

   It installs into every agent it detects on this machine; add `-a <agent>` (for example
   `-a claude-code`, `-a codex`, `-a cursor`) to install for yourself only. Without Node.js, save
   this file yourself as `publishport/SKILL.md` in your skills folder. In a hosted chat with no
   persistent skills folder, skip this step.

2. **Connect the user's account.**

   ```bash
   publishport login
   ```

   It prints an authorization link and a confirmation code, then exits. Give the user both, and
   ask them to open the link, sign in or create an account, check that the code matches, and
   click **Authorize**. Then run:

   ```bash
   publishport login --wait
   ```

   It returns as soon as they approve and saves the credential to
   `~/.publishport/config.json`. Exit code 3 means they have not approved yet: run it again.
   If you cannot talk to the user while a command runs, end your turn after sharing the link and
   run `--wait` when they reply. Links expire after 10 minutes; `publishport login` makes a new
   one.

   Do not ask the user to paste a token or an access address into the chat. If they already have
   one from the desktop app, `publishport login <address>` saves it directly.

3. **Check the machine side.**

   ```bash
   publishport capabilities
   ```

   It lists the user's online devices and which platforms are signed in on each. No device online
   means the user still needs the PublishPort desktop app (<https://www.publishport.app/download>),
   running and signed in with the same account. A platform shows as signed in once the user has
   logged into it in the desktop app.

Finish by telling the user what is ready and what is left for them to do.

The credential can run commands on the user's machine. Never print it, put it in a file inside a
project, or send it anywhere except PublishPort's own endpoints. In a sandbox that is thrown away
after the session, the login does not survive; `PUBLISHPORT_TOKEN` in the environment works in
its place.

## 1. Pick the channel

Publishing always goes through PublishPort's relay, which runs the command on the machine where
the user's desktop app is signed in. Two ways to reach that relay:

**a. The CLI** — the default. Every command goes through the relay, so it works whether or not
you are on the user's machine:

| What | CLI |
|---|---|
| Online devices, login state per platform | `publishport capabilities` |
| A platform's fast path plus its live `--help` schema | `publishport guide <platform> --device <d>` |
| Run one command on the device | `publishport run --device <d> -- <command...>` |
| Copy a file onto / off the device | `publishport upload` / `publishport download` |
| Anything else | `publishport call <tool> --json '{...}'` (`publishport tools` lists them) |

**b. PublishPort MCP tools are already connected** (`list_capabilities`, `local_bash`,
`publish_guide`, …) — use them instead and follow their own instructions, which are more
detailed than this file. They map one-to-one onto the CLI: `list_capabilities` =
`capabilities`, `publish_guide` = `guide`, `local_bash` = `run`, `prepare_upload` /
`read_local_file` = `upload` / `download`.

If neither works — no Node.js and no MCP tools — stop and tell the user what is missing.
Do not substitute scraping, headless logins, or unofficial platform APIs.

**Do not reach for a locally installed `ppcli` and run it yourself**, even when the desktop app is
on the same machine and you can see the binary. The relay is what resolves which device to run on,
checks login state, and keeps the run accounted for; going around it silently drops all three, and
breaks the moment the user's agent moves off that machine.

Everywhere below, `ppcli <platform> …` means *run that command through your channel* — as
`publishport run --device <d> -- ppcli <platform> …` on the CLI, or `local_bash` on MCP.

## 2. Publish

1. **Confirm the account.** `ppcli auth status` lists login state per platform, but it is cached
   and can be stale — before a real publish run `ppcli <platform> whoami`. If that reports
   `AUTH_REQUIRED`, ask the user to sign in again in the desktop app instead of pushing ahead.
2. **Read the real schema.** `publishport guide <platform> --device <d>` returns the fast path plus a
   one-line index of the platform's subcommands; for the full parameters of the one you need, run
   `ppcli <platform> <command> --help` (over MCP, pass `command` to `publish_guide`). Required arguments
   differ per platform (some need a cover image, a topic, a category id). Fill in every required
   argument deliberately; defaults are rarely what the user wants.
3. **Stage the content as files.** Put the body on the device first —
   `publishport call write_local_text --json '{"device":"<d>","path":"post.md","content":"…"}'`,
   or `write_local_text` over MCP — then pass it with `--file` (or the command's own
   `--<name>-file`). Never inline a long body in the command line: quoting breaks on the first

From karuha-m/publishport-skill, MIT.