md2wechat: a Go CLI that turns Markdown into WeChat drafts for AI agents

The gap md2wechat fills between a Markdown file and a WeChat draft

WeChat's official account editor is a browser form. Pasting Markdown into it loses structure, and inline styles have to be reapplied by hand. md2wechat's answer is to make each step of that pipeline a separate command with a machine-readable result, so a script or an agent can check state before it acts.

The README frames the tool as a CLI for the WeChat official account creation and publishing workflow, aimed at people driving it from Claude Code, Codex, WorkBuddy, Kimi Work, Hermes Agent, OpenClaw, or any other agent that can invoke a local binary. The repository is Go, with a thin npm wrapper: package.json declares the bin entry as scripts/run.js and a postinstall step in scripts/install.js, so the npm package downloads the matching GitHub Release bundle rather than shipping a JavaScript implementation.

The intended user is not someone who wants a GUI. It is someone who writes in Markdown, keeps credentials in a config file, and wants the publish step to be auditable.

Command boundaries: inspect, preview, convert, and where side effects happen

The design separates reading from writing. According to the README, inspect returns structured metadata, checks, readiness targets and blockers; preview writes only the final HTML returned by a successful API converter; convert performs the conversion and runs upload or draft side effects only when explicitly requested.

That distinction matters because a preview run cannot accidentally create a draft. The README states that the commands shown for preview and convert do not upload images or create drafts, and that creating a WeChat draft requires a separate invocation with --draft and --cover. If you pass the optional --wechat-account flag, the README requires the same account name on both the inspect and convert commands.

Agent integration is handled through discovery commands rather than a schema file: capabilities returns aggregated routing facts, doctor reports environment readiness, themes and layout list the available resources, and providers lists image backends. JSON goes to stdout as a single-line compact object terminated by a newline, and the README explicitly tells readers to pipe to jq rather than ask for indented output.

One documented failure mode is worth noting. In AI mode, preview returns PREVIEW_ACTION_REQUIRED and creates no output file, so anything that assumes a file exists after preview will break. The README directs you to inspect --json when you need readiness information instead.

Installing md2wechat and producing your first checked article

The README's quick start installs from npm. The package requires Node 18 or newer per the engines field in package.json, and the postinstall script fetches the platform binary from the GitHub Release.

npm install -g @geekjourneyx/md2wechat
md2wechat version --json
md2wechat config init --json
md2wechat config validate --json

After this you should see a version object, a generated config, and a validation result. The README notes that API mode preview and conversion need an md2wechat API key; the free AI mode instead produces a prompt for an external LLM.

With credentials configured, the first real use is a dry run that writes HTML to a local file and touches nothing remote:

md2wechat inspect article.md --json
md2wechat preview article.md --output preview.html
md2wechat convert article.md --output article.html

Open preview.html in a browser to see the rendered result. Only when you are satisfied do you add the side effects:

md2wechat inspect article.md --draft --cover cover.jpg --json
md2wechat convert article.md --draft --cover cover.jpg

The README also points to docs/INSTALL.md, docs/WECHAT-CREDENTIALS.md and docs/CONFIG-WALKTHROUGH.md for installation, WeChat credentials and IP whitelist setup. Those files are not reproduced here, so treat the credential steps as documented elsewhere rather than implied by the commands above.

The paid API boundary is the real decision point

md2wechat has two rendering paths, and the README's comparison table is blunt about the difference. In free AI mode the tool generates a prompt and an external LLM finishes the HTML; there are 3 basic themes, and :::module blocks are not parsed, appearing as ordinary paragraphs. In professional API mode the converter returns final WeChat HTML directly, with 48 themes and an API renderer that parses 56 recommended :::module syntax names.

The README prices the unified API at ¥199 as a one-time purchase, and lists multi-account support, a fixed WeChat interface egress, and pre-publish readiness checks as professional capabilities. The theme gallery and layout documentation are linked from the README rather than embedded in it.

This is a deliberate split, and it has consequences. If you evaluate only the free path, you are not evaluating the layout system the project is mostly about. Conversely, if your team cannot buy the key, the ::: syntax becomes dead weight in your Markdown files. The README also notes that local layout validate only checks syntax and cannot prove the remote renderer has deployed the module; you need an API preview or convert to confirm actual rendering.

Image generation, subject references, and plan mode

Cover and infographic generation is a separate command family. The README shows two ways to run it: directly through a configured image provider, or in plan mode where the host agent supplies its own image generation tool.

md2wechat prompts list --kind image --archetype cover --json
md2wechat generate_cover --article article.md --preset cover-semantic-concept
md2wechat generate_infographic --article article.md --preset infographic-claude-warm

Providers listed in the README include Volcengine, ModelScope, OpenRouter, OpenAI, Gemini, MiniMax and Atlas Cloud, with configuration in docs/IMAGE_PROVISIONERS.md. The README states that the authoritative preset list is whatever prompts list and prompts show return from the current binary, and that the documentation keeps only representative examples. That is a sensible stance for a project shipping releases this often, but it means the docs and the binary can drift.

The subject reference feature is narrow by design. The README says --subject-reference only works with the minimax provider's image-01 model, and the reference image must be a publicly reachable http(s) URL. If you need consistent character imagery on another provider, this flag will not help you. Plan mode is the opposite: it returns IMAGE_PLAN_READY, does not contact an image provider, does not require IMAGE_API_KEY, and does not upload to WeChat, but it only proceeds if the host runtime actually exposes an image generation tool.

Multi-platform drafts and the browser dependency

Version 3.6.0 added a workflow for saving the same Markdown into Zhihu, CSDN and Toutiao drafts. The mechanism is unusual: md2wechat prepares the content locally, and the host agent then drives an already logged-in browser through built-in steps.

md2wechat sync prepare article.md --output ./article-prepared --json
md2wechat skills read md2wechat references/sync/workflow.md --json

The README is careful about what prepare means: the result is waiting for the host to act, and does not mean a draft has been created. Platform-specific steps, image handling, Toutiao title limits and recovery are in docs/SYNC.md.

The dependency here is real. This path needs an agent with browser control and an existing logged-in session. A plain shell script cannot complete it, and a headless CI job without that session cannot either. The README also advises reopening the saved draft to verify it. If your environment has no browser-capable agent, this feature is not available to you regardless of the CLI version.

Licence, maintenance and upgrade cost

The repository is not archived, and the last push was on 2026-09-12, with v3.6.0 released the same day after v3.5.0 on 2026-09-07 and v3.4.0 on 2026-09-01. That cadence is fast enough that you should read CHANGELOG.md before pinning a version.

Licensing is the part to check yourself. The README badge reads Source Available, package.json says SEE LICENSE IN LICENSE, and the repository metadata reports NOASSERTION. Those three signals do not add up to an OSI-approved licence, and the README separately sells a paid API key. Before you ship this inside a product, read LICENSE in full; nothing here is legal advice, and the distinction between source-available and open source affects redistribution and commercial use.

Upgrade cost is mostly version skew. Discovery commands exist precisely so an agent can ask the installed binary what it supports, and the README tells you to confirm sync support with capabilities --json before using it. The release bundle is fetched at npm postinstall time, so upgrading means reinstalling the npm package rather than swapping a single file. Brand Profile preferences live in ~/.config/md2wechat/brand.md and survive upgrades, but any layout module you adopt is only as available as the remote renderer behind your API key.

Editorial conclusion

Adopt md2wechat if your workflow already lives in a terminal or an agent that can call a local CLI and you accept that the 48 themes and ::: layout modules only render in paid API mode. Do not adopt it if you need a fully offline converter or refuse a per-seat API key. Before committing, run md2wechat doctor --json and md2wechat config validate --json against your own credentials, and confirm with md2wechat capabilities --json that your installed version supports the sync commands.

Frequently asked questions

Official sources

1. geekjourneyx/md2wechat-skill on GitHub
2. Issues
3. Project website
4. README
5. Releases