Picsart CLI & MCP — Docs

Public developer documentation for the Picsart gen-ai CLI, the Picsart MCP server, and drop-in Skills — generate image, video, and audio across 141 models from 28 providers, from your terminal or any AI agent. Built with VitePress.

• Source of truth: this folder (docs-site/) inside the ai-toolkit repo.

• Public repo: https://github.com/PicsArt/picsart-mcp-cli-docs

• Live wiki (public, no Actions needed): https://github.com/PicsArt/picsart-mcp-cli-docs/wiki

• Themed site (when Actions enabled): https://picsart.github.io/picsart-mcp-cli-docs/

Local development

cd docs-site
npm install
npm run dev        # http://localhost:5173 (or --port 4600)
npm run build      # static build → .vitepress/dist
npm run preview    # preview the production build

Related MCP server: Fal.ai MCP Server

Structure

docs-site/
  .vitepress/config.ts        # nav, sidebar (unified), theme
  .vitepress/theme/           # Picsart brand + ModelCatalog / ProviderGrid Vue components + data/
  index.md                    # home (hero)
  guide/                      # getting started + CLI / MCP / Skills + concepts
  reference/                  # model reference: catalog, per-mode, per-provider
    providers/                # one page per vendor (28)
  scripts/build-wiki.py       # converts these docs → GitHub Wiki markdown

Data freshness

.vitepress/theme/data/{models,providers}.json are generated from the live catalog (gen-ai models --json). Regenerate them when the catalog changes so the Model Catalog, Providers grid, and the generated wiki tables stay accurate.

Publishing

The docs live in PicsArt/picsart-mcp-cli-docs (public). There are two delivery surfaces; keep both in sync from this docs-site/ source.

One-time / occasional: sync source to the public repo

The public repo's main mirrors this docs-site/ folder at its root. To update it:

# from a clean checkout of docs-site/ contents (root of the public repo)
git add -A && git commit -m "docs: <what changed>"
git push origin main

The ai-toolkit monorepo is private; never push its history to the public repo. Only the docs-site/ contents (at the public repo root) + .github/workflows/deploy-docs.yml belong there.

Route A — GitHub Pages (themed, interactive)

.github/workflows/deploy-docs.yml builds and deploys on every push to main. It derives the base path from the repo name (DOCS_BASE=/<repo>/).

Requires GitHub Actions enabled for the repo. The PicsArt org disables Actions by default, so a PicsArt org admin must allow it (org → Settings → Actions, or add the repo to the allowlist). Once enabled:

gh workflow run deploy-docs.yml --repo PicsArt/picsart-mcp-cli-docs --ref main

Route B — GitHub Wiki (plain, no Actions) ← currently live

GitHub renders the wiki server-side, so it needs no Actions/Pages build. Plain Markdown, so the interactive catalog/provider grids become static tables.

First-page caveat: GitHub has no API to create a wiki's first page. Create one page via the web UI once (/wiki → "Create the first page" → Save). After that, .wiki.git is pushable and the steps below keep it in sync.

# 1. clone the wiki (separate git repo)
git clone https://github.com/PicsArt/picsart-mcp-cli-docs.wiki.git .wiki

# 2. regenerate all wiki pages from these docs (47 pages: guide + reference + 28 providers + Home/_Sidebar/_Footer)
npm run wiki:build -- .wiki        # = python3 scripts/build-wiki.py .wiki

# 3. publish
cd .wiki
git add -A && git commit -m "docs: sync wiki"
git push origin master             # GitHub wikis use the 'master' branch

scripts/build-wiki.py strips VitePress frontmatter, rewrites /guide and /reference links to wiki page names, converts :::tip/warning containers to blockquotes, and replaces the <ModelCatalog> / <ProviderGrid> components with static tables built from the data JSON.