Create videos, images, written content, social posts, articles and decks from a terminal or an AI agent. Node.js 20 or newer is required. The package includes usemo and usemo-mcp; neither needs Python, the backend, or a local database.

Install

npm install -g @usemo.com/sdk@0.1.0
usemo --version
usemo --help

For a one-off command without a global install:

npx --yes --package @usemo.com/sdk@0.1.0 usemo --help

Install from this repository

cd sdk/javascript
npm ci
npm install -g .
usemo --version
usemo --help

To distribute the client without the backend, run npm pack in this directory and install the resulting tarball with npm install -g /path/to/usemo-sdk-0.1.0.tgz. The package contains only client source, its generated schemas, and this guide.

Authenticate

Create a workspace key in UseMo → Settings → API Keys. Supply it through USEMO_API_KEY from your secret manager. To save an existing key as a local profile:

printf '%s\n' "$USEMO_API_KEY" | usemo login --key-stdin --profile work
usemo whoami --profile work --json
usemo profiles list
usemo profiles use work

Login verifies the key with a workspace read before saving it. It does not create an account or a key. Browser/device login is not implemented in this CLI. The existing hosted MCP connector has its own OAuth flow when enabled by the deployment.

Profiles are stored as plaintext in ~/.config/usemo/config.json, with directory mode 0700 and file mode 0600. Override the directory with USEMO_CONFIG_DIR or XDG_CONFIG_HOME. Environment keys take precedence over the selected profile. --profile takes precedence over USEMO_PROFILE, then the saved active profile. --base-url takes precedence over USEMO_API_BASE, then the profile's base URL, then https://api.usemo.com. /api and /api/v1 suffixes are accepted.

Saved keys are bound to their original host: changing the API host requires a separate login/profile or explicitly supplying USEMO_API_KEY. HTTPS is required except for loopback development. Keys are sent through X-API-Key, matching the current REST implementation. USEMO_WORKSPACE_ID is optional for a scoped API key. usemo logout removes the selected local profile; revoke keys separately in the app.

Create media and content

# Validate and inspect the request without credentials or API calls
usemo images create "A green ceramic vase in a sunlit studio" --dry-run --json

# Create an image and wait for its result URLs
usemo images create "A green ceramic vase in a sunlit studio" --wait --json

# Brief → grounded storyboard → finished video
usemo videos create "A 30-second product launch video for our brand" --wait --json

# Animate an existing frame (use an actual image URL or asset ID)
usemo videos generate "A slow camera push toward the product" \
  --input-image-url https://example.com/product.png --duration-sec 5 --wait --json

usemo content create "Write a LinkedIn post announcing our launch" --wait --json
usemo content social "Meet our new product" --cta "Explore now" --wait --json
usemo content article "How to choose a team phone system" --wait --json
usemo content deck "Product launch" --brief "Overview, audience, benefits and next steps" --wait --json

Generation spends workspace credits. Commands execute the requested operation without interactive confirmation. Use --dry-run to review a request. A video brief uses asynchronous planning by default to avoid gateway timeouts. It may initially return planning: true, shippable: null, and a job handle. A synchronous brief (--async-plan=false) can return shippable: false when the grounding gate blocks it; that is a planning result and no render job has been submitted. Refine the brief or brand context. Written content may return synchronously, or return a nested job handle; --wait handles both forms. Other creation responses contain asynchronous jobs.

usemo brand get --json
usemo brand learn https://example.com --wait --json
usemo ideas suggest "Announce our new product" --json
usemo videos plan "A 30-second launch video" --json
usemo videos quote --data @quote.json --json
usemo jobs list --status processing --json
usemo jobs get JOB_ID --json
usemo jobs wait JOB_ID --max-wait-sec 600 --json
usemo assets list --type image --json
usemo twins list --json

For a quote, quote.json contains {"storyboard": ...} using the actual storyboard returned by planning. campaigns quote accepts a concepts array. Twin rendering uses twins render TWIN_ID --audio-asset-id AUDIO_ID; voice generation uses twins speak TWIN_ID --script-text "Your script".

Agent and automation contract

usemo schema [GROUP COMMAND] --json provides input JSON Schema, descriptions, annotations and routes. usemo discover QUERY --json searches the command catalog.
Field flags use dashes (--num-images); JSON uses underscores (num_images). Nested objects/arrays can be supplied as JSON flags or through --data.
--data accepts an inline object, @file.json, or @- for stdin. Duplicate flags and duplicate fields between JSON and flags are rejected.
--json emits a single JSON value on stdout. Errors are JSON on stderr. Exit codes: 0 success, 1 API/auth/network/local error, 2 invalid input, 3 wait timeout, 4 failed/cancelled job. shippable: false is a successful planning response; inspect it before assuming media was generated.
--out receipt.json saves JSON without overwriting an existing file. Use usemo download HTTPS_URL --out video.mp4 to download a result URL. Downloads stream to a temporary file and publish atomically, do not overwrite, and never send an API key to the media host. Redirecting asset URLs are rejected; retrieve a direct URL from the library if necessary.
Submission timeout defaults to 60 seconds (--timeout). Waiting defaults to 180 seconds and polls every 5 seconds (--wait-timeout, --poll-interval). The explicit jobs wait tool supports max_wait_sec 5–600 and poll_interval_sec 2–30. A wait timeout leaves the remote job running and returns its handle. Resume waiting instead of resubmitting.
Image generation, direct video generation, video creation and text generation accept --idempotency-key. The client generates one if omitted and includes it in the receipt or ambiguous-submission error. Reuse the same key and payload for a retry. No requests are automatically retried. Other endpoints are not assumed to implement idempotency.
doctor is an offline configuration check and does not print secrets. whoami verifies access through the brand-profile endpoint; it does not claim to return a complete identity/scopes record.

For API capabilities outside the curated catalog:

usemo request GET /api/v1/assets --query job_id=JOB_ID --query offset=20 --json
usemo request POST /api/v1/jobs/JOB_ID/cancel --dry-run --json

Generic requests use the selected API origin only. Read the current REST schema for advanced payloads. CLI dry runs validate curated inputs, but cannot verify server permissions, available credits, remote asset URLs, or runtime model health.

Connect MCP

Without a global installation, configure your MCP client to launch the npm package:

{
  "mcpServers": {
    "usemo": {
      "command": "npx",
      "args": ["--yes", "--package", "@usemo.com/sdk@0.1.0", "usemo-mcp"],
      "env": { "USEMO_PROFILE": "work" }
    }
  }
}

With the package globally installed, configure an MCP client to launch:

{
  "mcpServers": {
    "usemo": {
      "command": "usemo-mcp",
      "env": { "USEMO_PROFILE": "work" }
    }
  }
}

A saved profile or a USEMO_API_KEY supplied by the host provides authentication. If a GUI cannot resolve the executable on PATH, use its absolute installed path, or node with the absolute path to this package's src/mcp.js. usemo mcp --profile work is the equivalent CLI entry point. Protocol messages are the only stdout output. The server exposes 24 tools, including offline usemo_get_started and usemo_discover_tools. Local tool inputs are flat objects as advertised by tools/list; follow the actual schema exposed by your transport.

The existing remote connector remains at https://api.usemo.com/mcp:

{
  "mcpServers": {
    "usemo": { "url": "https://api.usemo.com/mcp" }
  }
}

Remote clients must supply their own API key or complete the deployment's OAuth flow. Enabling OAuth and deploying backend changes are separate release steps. New tools in this checkout are not available on the hosted endpoint until deployed.

JavaScript API

import { UseMoClient } from '@usemo.com/sdk';

const usemo = new UseMoClient({ apiKey: process.env.USEMO_API_KEY });
const result = await usemo.run('images create', {
  prompt: 'A green ceramic vase in a sunlit studio',
  idempotency_key: 'my-unique-workflow-step-id'
}, { wait: true, timeout: 300 });
console.log(result);

Development and release checks

npm ci
npm test
# From the repository root, using its development Python environment:
.venv/bin/python sdk/javascript/scripts/export_catalog.py --check

The catalog is generated from app/mcp/tools.py and the public collateral request models. After changing those inputs, regenerate it with the same command without --check. CI verifies that the checked-in catalog stays current. Tests use mocked HTTP, a loopback API, and actual MCP SDK transports; they do not spend credits or render real media. Validate a release with a real workspace key and representative generations before publishing to npm and deploying the hosted tools.