/setup

name: setup
description: "One-time setup of image and video generation credentials, verified before use. \"set up my API keys\""
argument-hint: "[--image | --video | --fallback | --status | --reset]"
effort: low
user-invocable: true

/socialforge:setup — API Credential Configuration

> **Script location.** If your host does not set `${CLAUDE_PLUGIN_ROOT}`, the scripts are in this plugin's `scripts/` folder, next to `skills/`. Run them with Python 3.10 or newer: `python`, or `python3` where `python` is not found (macOS, many Linux systems).

One-time setup that records where each credential lives. A key kept in an environment variable is never written anywhere: setup records the variable name and the scripts read the value each time. See Security Notes for what is stored where.

Context efficiency

Asset-heavy skill. **Grep before Read** the asset catalog (`${CLAUDE_PLUGIN_DATA}/socialforge/brands/<brand>/asset-index.json`) — never list the asset directory. Reference generated images / videos by path, not by loading metadata. Brand profile loads once per session.

What This Does

Configures two services that SocialForge needs for creative production:

1. **Google Cloud Vertex AI** (required for images) — the image models, resolved at run time from the registry aliases `latest-image-balanced-google` and `latest-image-google` 2. **WaveSpeed** (required for video) — image-to-video, resolved from the registry alias `latest-video-wavespeed`

Prerequisites

Your admin provides you with:

• A **Google Cloud service account JSON file** (for image generation)
• A **WaveSpeed API key** (for video generation)

If you are the admin, see the Admin Setup section below.

How to Run

/socialforge:setup

Interactive Flow

Step 0: Check Dependencies (nothing installs without your yes)

Run this first. It only REPORTS which packages are present and prints the exact pinned install command for each one that is missing; it installs nothing:

python "${CLAUDE_PLUGIN_ROOT}/scripts/install_deps.py"

Packages it checks by default (every version is pinned in `scripts/install_deps.py`): Pillow (compositing), google-genai (Vertex AI), wavespeed and imageio-ffmpeg (video), playwright (carousels; its Chromium browser is a large download).

Show the user the list, then ask:

These packages are missing: <list>. Install them now with the pinned versions? (yes / no)
  Playwright's browser (for carousels) is a large download; say so if playwright is on the list.

Only on an explicit `yes`, run:

python "${CLAUDE_PLUGIN_ROOT}/scripts/install_deps.py" --install

Any other answer: print the pinned commands from the report for the user to run themselves, and continue.

Extra packages are never part of that default and are installed only when the user asks for them by name: HiggsField's client (`--groups higgsfield`), background removal, which fetches model weights on first use (`--groups background-removal`), C2PA signing (`--groups c2pa`), and OS keychain support (`--groups keyring`), which lets a key you type or pipe in be kept in the keychain instead of a plain-text file.

Step 1: Image Generation (Vertex AI)

Check if already configured:

python "${CLAUDE_PLUGIN_ROOT}/scripts/credential_manager.py" status

If not configured, ask:

Image Generation Setup (Google Cloud Vertex AI)

Do you have a Google Cloud service account JSON file?
  Provide the full file path (e.g., C:\Users\you\Downloads\socialforge-credentials.json)

Or type "skip" to configure later (image generation will not work).

When user provides the path:

python "${CLAUDE_PLUGIN_ROOT}/scripts/credential_manager.py" setup-vertex --json-path "<user-provided-path>"

The script records the file's PATH and uses the file where it is; it makes no copy. Tell the user to keep the file there, readable only by them. If the result carries `warnings` about an older SocialForge copy (`gcp-credentials.json`, made before 1.31.0), show it: that copy is no longer used, and deleting it is the user's call.

Show the result. If success:

Image generation configured.
  Project: <project_id>
  Service Account: <email>
  Models: resolved at run time from the registry (aliases latest-image-balanced-google, latest-image-google)

Step 2: Video Generation (WaveSpeed)

Video Generation Setup (WaveSpeed)

Do you have a WaveSpeed API key?
  Do NOT paste it here: anything typed into this chat is stored in the conversation transcript.
  Set it as the environment variable WAVESPEED_API_KEY (in your shell or your host's environment
  settings) and tell me when it is set.

Or type "skip" to configure later (video generation will not work).

When the user says it is set, run the command below. The script reads `WAVESPEED_API_KEY` and records only the variable name; the key itself is never written, and it is read from the environment each time a video is made. `--api-key` is refused with exit 2 (a key on the command line lands in shell history and the process table). The script never reads stdin on its own, so with no key it stops at once with exit 2 (`no key: set WAVESPEED_API_KEY, or use --api-key-stdin`) instead of waiting: tell the user the variable is not visible to this shell and ask them to set it where the host can see it.

If the variable cannot stay set across sessions, the user can store the key once from their own terminal with `--prompt` (a hidden prompt, real terminal only); `--api-key-stdin` reads one line from stdin. A key given either way goes to the OS keychain when `keyring` is installed (`--groups keyring` above), and otherwise to `credentials.json` in plain text, with a warning in the result: show that warning to the user.

python "${CLAUDE_PLUGIN_ROOT}/scripts/credential_manager.py" setup-wavespeed

Show the result. If success:

Video generation configured.
  Provider: WaveSpeed (alias latest-video-wavespeed)
  Models: image-to-video, text-to-video