CLI Guide

Use `mini-cms` to initialize config, pull, push, generate a browser client, install a local skill, list collections, and inspect collection items.

mini-cms is the command-line tool for developer-driven schema management.

Configuration Sources

The CLI resolves values in this order:

command flags like --project-id
values in mini.config.json
environment variables with the MINI_CMS_ prefix

Supported environment variables:

MINI_CMS_BASE_URL=
MINI_CMS_WORKSPACE_ID=
MINI_CMS_PROJECT_ID=
MINI_CMS_API_KEY=

Example:

export MINI_CMS_BASE_URL=https://mini-cms-rosy.vercel.app
export MINI_CMS_WORKSPACE_ID=org_abc123
export MINI_CMS_PROJECT_ID=project_default_xyz789
export MINI_CMS_API_KEY=mcms_test_123

mini-cms pull

What It Does

connects your local project to a Mini CMS workspace
creates mini.config.json with an interactive setup flow
pulls collection schemas into local files
pushes schema changes back to the dashboard workspace
generates TypeScript types for your content model
generates a fetch-based browser client and declaration file from local mini.* files
installs a local .skills/mini-cms-cli/SKILL.md helper for coding agents
lists collections or collection items for debugging and automation

Run The CLI

After installing the CLI, run:

mini-cms --help

Generate An API Key

Sign in to the dashboard.
Open API Keys.
Create a workspace-scoped or collection-scoped key.
Copy the key and keep it somewhere secure.

First Pull

Start with interactive setup:

mini-cms init

Or create the config directly with flags:

mini-cms init \
  --base-url https://mini-cms-rosy.vercel.app \
  --workspace-id <workspace-id> \
  --api-key <api-key> \
  --project-id <project-id>

Then pull your project schema:

Your first pull can create mini.config.json, mini.collections.json, and mini.types.ts.

mini-cms pull \
  --base-url https://mini-cms-rosy.vercel.app \
  --workspace-id <workspace-id> \
  --project-id <project-id> \
  --api-key <api-key>

Files The CLI Uses

File	Generated By	Used By	Description
`mini.config.json`	`pull`, `generate`	all commands	Saved connection defaults and local output paths.
`mini.collections.json`	`pull`	`push`, `generate`	Pulled or hand-edited collection definitions.
`mini.types.ts`	`pull`, `generate`	your app code	Generated TypeScript content types.
`mini.client.js`	`generate`	browser or app code	Fetch-based Mini CMS client for the public content API.
`mini.client.d.ts`	`generate`	TypeScript projects	Type declarations for `mini.client.js`.

JSON Schema files are available in the repo and are also served by the web app:

packages/cli/schemas/mini.config.schema.json
packages/cli/schemas/mini.collections.schema.json
/schemas/mini.config.schema.json
/schemas/mini.collections.schema.json

File Schemas

`mini.config.json`

Example:

{
  "$schema": "https://mini-cms-rosy.vercel.app/schemas/mini.config.schema.json",
  "baseUrl": "https://mini-cms-rosy.vercel.app",
  "workspaceId": "org_123",
  "projectId": "project_123",
  "apiKey": "mcms_test_123",
  "collectionId": "col_123",
  "collectionsPath": "mini.collections.json",
  "typesPath": "mini.types.ts",
  "clientPath": "mini.client.js",
  "declarationsPath": "mini.client.d.ts"
}

Field	Type	Required	Description
`baseUrl`	`string`	Yes	Base URL for your Mini CMS app.
`workspaceId`	`string`	Yes	Workspace ID used by CLI commands and generated files.
`projectId`	`string`	Required for `pull` and `push`	Default project ID for project-scoped schema sync and generated browser client requests.
`apiKey`	`string`	No for `generate`, Yes for protected commands	API key for schema sync and protected list endpoints.
`collectionId`	`string`	No	Optional default collection scope for pull, push, or generate.
`collectionsPath`	`string`	No	Path to the collection definitions file or directory.
`typesPath`	`string`	No	Output path for generated TypeScript types.
`clientPath`	`string`	No	Output path for generated browser client JavaScript.
`declarationsPath`	`string`	No	Output path for generated browser client declarations.

`mini.collections.json`

Example:

{
  "$schema": "https://mini-cms-rosy.vercel.app/schemas/mini.collections.schema.json",
  "workspaceId": "org_123",
  "pulledAt": "2026-03-09T12:00:00.000Z",
  "collections": [
    {
      "id": "col_testimonials",
      "name": "Testimonials",
      "slug": "testimonials",
      "description": "Client quotes and endorsements",
      "schema": [
        { "key": "title", "label": "Title", "type": "text" },
        { "key": "publishedAt", "label": "Published At", "type": "date" },
        { "key": "featured", "label": "Featured", "type": "boolean" }
      ]
    }
  ]
}

You can use the $schema field to get editor validation and autocomplete for these files.

Top-level fields:

Field	Type	Required	Description
`workspaceId`	`string`	No	Included when the file was created by `pull`.
`pulledAt`	`string`	No	ISO timestamp showing when the file was last pulled.
`collections`	`Collection[]`	Yes	Array of collection definitions used by `push` and `generate`.

Collection fields:

Field	Type	Required	Description
`id`	`string`	No	Existing collection ID from the dashboard.
`name`	`string`	Yes	Human-readable collection name.
`slug`	`string`	Yes	URL-safe identifier for the collection.
`description`	`string \| null`	No	Optional description shown in the dashboard.
`schema`	`CollectionField[]`	Yes	Fields that define each item shape.

Collection field syntax:

Field	Type	Required	Description
`key`	`string`	Yes	Stored field key. Must not start with `_`.
`label`	`string`	Yes	Human-readable field label.
`type`	`"text" \| "url" \| "number" \| "boolean" \| "date"`	Yes	Supported Mini CMS field type.

`mini.types.ts`

This file is generated. Example shape:

export const workspaceId = "org_123" as const;

export type CollectionSlug =
  | "testimonials";

export type TestimonialsItem = {
  title: string;
  publishedAt: string;
  featured: boolean;
};

export type CollectionMap = {
  "testimonials": TestimonialsItem;
};

export type CollectionItem<T extends CollectionSlug> = CollectionMap[T];

Key exports:

Export	Type	Description
`workspaceId`	string literal	The workspace ID used during generation.
`CollectionSlug`	union type	Union of all collection slugs.
`<CollectionName>Item`	type alias	Generated item type for each collection.
`CollectionMap`	mapped object type	Maps collection slugs to item types.
`CollectionItem<T>`	generic type	Looks up an item type from a slug.

`mini.client.js`

This file is generated. It exports a fetch-based browser client.

The generated declaration file makes the client type-safe against your collection slugs and item shapes.

Main exports:

Export	Type	Description
`miniCmsConfig`	object	Embedded default `baseUrl`, `workspaceId`, and `projectId`.
`getMiniCmsCollections()`	function	Returns generated collection metadata.
`client.collectionDefinitions`	array	Generated collection metadata array.
`client.collections`	object	Collection query helpers keyed by JS-safe collection slug.
`createMiniCmsClient()`	function	Creates a client with `getCollectionItems()`.

Example usage:

import { createMiniCmsClient } from "./mini.client.js";

const client = createMiniCmsClient();

const response = await client.getCollectionItems("testimonials");

response.items[0]?.title;

const sameResponse = await client.collections.testimonials.query();

sameResponse.items[0]?.title;

Hyphenated slugs are converted into JS-safe helper keys:

await client.collections.case_studies.query();

If you need request overrides, pass them as the second argument:

const filtered = await client.getCollectionItems("testimonials", {
  page: 2,
  query: "acme",
  filters: { featured: true },
});

getCollectionItems(collectionSlug, options?) option fields:

Field	Type	Required	Description
`collectionId`	`string`	No	Direct collection ID override if you need to bypass the generated slug lookup.
`workspaceId`	`string`	No	Overrides the default workspace ID.
`projectId`	`string`	No	Overrides the default project ID.
`page`	`number`	No	1-based page number.
`limit`	`number`	No	Page size.
`query`	`string`	No	Text search sent as `q`.
`filters`	`Record<string, string \| number \| boolean>`	No	Exact-match filters sent as `filter.<fieldKey>`.
`headers`	`HeadersInit`	No	Extra request headers for `fetch`.

`mini.client.d.ts`

This file is generated for TypeScript projects using mini.client.js.

Key declarations:

Export	Type	Description
`MiniCmsCollectionDefinition`	type	Collection metadata shape.
`MiniCmsCollectionSlug`	type	Union of generated collection slugs.
`MiniCmsCollectionMap`	type	Maps collection slugs to generated item types.
`MiniCmsCollectionItem<T>`	generic type	Looks up the generated item type for a collection slug.
`MiniCmsClientConfig`	type	Overrides for `baseUrl`, `workspaceId`, and `projectId`.
`MiniCmsGetCollectionItemsOptions<T>`	generic type	Options shape for `getCollectionItems(collectionSlug, options?)`.
`MiniCmsCollectionItemsResponse<T>`	generic type	Response shape returned by the public API client with typed `items`.

Create A Collection From Code

Edit mini.collections.json or point mini-cms to a directory of JSON collection files.

Example collection definition:

{
  "collections": [
    {
      "name": "Testimonials",
      "slug": "testimonials",
      "description": "Client quotes and endorsements",
      "schema": [
        { "key": "title", "label": "Title", "type": "text" },
        { "key": "publishedAt", "label": "Published At", "type": "date" }
      ]
    }
  ]
}

_id and _published are built-in system fields, so you should not define custom fields that start with _.

Push Local Schema

mini-cms push

You can also override the input path:

mini-cms push --collections ./collections

Pull Remote Schema

mini-cms pull

To restrict to one collection:

mini-cms pull --collection-id <collection-id>

Generate Browser Client

Use your local mini.config.json and mini.collections.json to generate a simple fetch-based client and declaration file.

mini-cms generate --project-id <project-id>

This writes mini.client.js and mini.client.d.ts by default.

Install The CLI Skill

Install the packaged CLI skill into the current project root.

mini-cms add-skill

This writes:

.opencode/skills/mini-cms-cli/SKILL.md

Project Commands

mini-cms list-projects
mini-cms project create --name "Website" --slug website
mini-cms project delete website

Collection Commands

mini-cms list-collections
mini-cms collection create --name "Testimonials" --slug testimonials --schema ./schema.json
mini-cms collection delete testimonials
mini-cms collection item list testimonials --page 1 --limit 25
mini-cms collection item insert testimonials --items="title=Hello;published=true"
mini-cms collection item insert testimonials --items-file ./items.json
cat ./items.json | mini-cms collection item insert testimonials
mini-cms collection item update testimonials --id="item_123" --value="title=Updated"
mini-cms collection item delete testimonials --id="item_123"

Commands

Command	Purpose	Reads	Writes
`mini-cms pull`	Pull project-scoped remote schema into local files.	`mini.config.json`	`mini.config.json`, `mini.collections.json`, `mini.types.ts`
`mini-cms init`	Create `mini.config.json` with interactive prompts.	-	`mini.config.json`
`mini-cms push`	Push local collection definitions to the configured project.	`mini.config.json`, `mini.collections.json`	-
`mini-cms list-projects`	List workspace projects.	`mini.config.json`	-
`mini-cms project create`	Create a project.	`mini.config.json`	-
`mini-cms project delete <slug-or-id>`	Delete a project.	`mini.config.json`	-
`mini-cms list-collections`	List collections for the current workspace or project.	`mini.config.json`	-
`mini-cms collection create`	Create a collection.	`mini.config.json`	-
`mini-cms collection delete <slug-or-id>`	Delete a collection.	`mini.config.json`	-
`mini-cms collection item list <slug-or-id>`	List items in a collection.	`mini.config.json`	-
`mini-cms collection item insert <slug-or-id>`	Insert one item with `--items` or many with `--items-file`.	`mini.config.json`	-
`mini-cms collection item update <slug-or-id>`	Update an item in a collection.	`mini.config.json`	-
`mini-cms collection item delete <slug-or-id>`	Delete an item from a collection.	`mini.config.json`	-
`mini-cms generate`	Generate a fetch-based browser client from local config and collection files.	`mini.config.json`, `mini.collections.json`	`mini.config.json`, `mini.types.ts`, `mini.client.js`, `mini.client.d.ts`
`mini-cms add-skill`	Install the packaged CLI skill into the current project.	-	`.opencode/skills/mini-cms-cli/SKILL.md`

Detailed Command Reference

`mini-cms init`

Interactive setup that creates mini.config.json with prompts for base URL, workspace ID, project ID, and API key.

mini-cms init

Interactive Prompts

When run without flags, init prompts for:

Base URL: Your deployed Mini CMS instance (e.g., https://mini-cms-rosy.vercel.app)
Workspace ID: The workspace to connect to (e.g., org_abc123)
Project ID: Default project for pull/push operations (optional)
API Key: Your API key for protected operations (optional)
Collections Path: Where to save pulled collections (default: mini.collections.json)
Types Path: Where to save generated types (default: mini.types.ts)

Non-Interactive Mode

Pass flags directly to skip prompts:

mini-cms init \
  --base-url https://mini-cms-rosy.vercel.app \
  --workspace-id org_abc123 \
  --project-id project_default_xyz789 \
  --api-key mcms_test_123

If MINI_CMS_BASE_URL, MINI_CMS_WORKSPACE_ID, MINI_CMS_PROJECT_ID, or MINI_CMS_API_KEY are set, init uses them as defaults before prompting.

Options

Option	Type	Description
`--config`	string	Output path for `mini.config.json`. Default: `./mini.config.json`
`--base-url`	string	Set the base URL directly
`--workspace-id`	string	Set the workspace ID
`--project-id`	string	Set the default project ID
`--api-key`	string	Set the API key
`--collection-id`	string	Set default collection ID
`--collections`	string	Collections file path
`--types`	string	Types output path
`--client`	string	Client output path
`--declarations`	string	Declarations output path

Output

Creates mini.config.json:

{
  "baseUrl": "https://mini-cms-rosy.vercel.app",
  "workspaceId": "org_abc123",
  "projectId": "project_default_xyz789",
  "apiKey": "mcms_test_123"
}

Use Cases

First-time setup for a new project
Re-initializing after deleting mini.config.json
Creating multiple config files for different environments

`mini-cms pull`

Downloads the remote schema from a project and saves it to local files.

mini-cms pull --project-id <project-id>

What It Does

Connects to the configured Mini CMS instance
Fetches all collections in the specified project
Writes mini.collections.json with collection definitions
Generates mini.types.ts with TypeScript types
Updates mini.config.json with the project ID

Basic Usage

# Pull all collections from a project
mini-cms pull --project-id project_default_xyz789

# With config file
mini-cms pull

Pull a Single Collection

# Only pull one collection by ID
mini-cms pull --project-id project_default_xyz789 --collection-id col_testimonials

Options

Option	Type	Required	Description
`--base-url`	string	No*	Mini CMS base URL (*if not in config)
`--workspace-id`	string	No*	Workspace ID (*if not in config)
`--project-id`	string	Yes	Project scope for the pull
`--api-key`	string	No*	API key (*if not in config)
`--collection-id`	string	No	Restrict pull to one collection
`--collections`	string	No	Output path for `mini.collections.json`
`--types`	string	No	Output path for `mini.types.ts`

Output Files

mini.collections.json:

{
  "workspaceId": "org_abc123",
  "pulledAt": "2026-03-11T10:30:00.000Z",
  "collections": [
    {
      "id": "col_testimonials",
      "name": "Testimonials",
      "slug": "testimonials",
      "description": "Client quotes",
      "schema": [
        { "key": "title", "label": "Title", "type": "text" },
        { "key": "featured", "label": "Featured", "type": "boolean" }
      ]
    }
  ]
}

mini.types.ts:

export const workspaceId = "org_abc123" as const;
export type CollectionSlug = "testimonials";
export type TestimonialsItem = {
  title: string;
  featured: boolean;
};
export type CollectionMap = {
  "testimonials": TestimonialsItem;
};
export type CollectionItem<T extends CollectionSlug> = CollectionMap[T];

Use Cases

Setting up a new local project
Syncing schema changes made in the dashboard
Generating TypeScript types for your content model

`mini-cms push`

Uploads local collection definitions to the remote project.

mini-cms push --project-id <project-id>

What It Does

Reads collection definitions from mini.collections.json (or a directory)
Creates any collections that don't exist in the project
Updates existing collections with new schema fields
Preserves existing items in updated collections

Basic Usage

# Push all collections from default file
mini-cms push --project-id project_default_xyz789

# Push from a directory of collection files
mini-cms push --project-id project_default_xyz789 --collections ./collections

Input File Format

Single file (mini.collections.json):

{
  "collections": [
    {
      "name": "Testimonials",
      "slug": "testimonials",
      "description": "Client quotes",
      "schema": [
        { "key": "title", "label": "Title", "type": "text" }
      ]
    }
  ]
}

Directory (each file is a collection):

collections/
  testimonials.json
  partners.json

Each file:

{
  "name": "Testimonials",
  "slug": "testimonials",
  "schema": [
    { "key": "title", "label": "Title", "type": "text" }
  ]
}

Options

Option	Type	Required	Description
`--base-url`	string	No*	Mini CMS base URL (*if not in config)
`--workspace-id`	string	No*	Workspace ID (*if not in config)
`--project-id`	string	Yes	Target project for push
`--api-key`	string	No*	API key (*if not in config)
`--collection-id`	string	No	Restrict push to one collection
`--collections`	string	No	Input file or directory

Use Cases

Deploying schema changes from local code to the dashboard
Creating new collections programmatically
Syncing field changes across environments

`mini-cms generate`

Creates a fetch-based browser client and TypeScript types from local collection files.

mini-cms generate --project-id <project-id>

What It Does

Reads mini.collections.json for collection definitions
Generates mini.types.ts with TypeScript types
Generates mini.client.js with a fetch-based client
Generates mini.client.d.ts with type declarations

Basic Usage

# Generate with default paths
mini-cms generate --project-id project_default_xyz789

# Custom output paths
mini-cms generate \
  --project-id project_default_xyz789 \
  --types ./src/cms-types.ts \
  --client ./src/cms-client.js \
  --declarations ./src/cms-client.d.ts

Options

Option	Type	Required	Description
`--base-url`	string	No*	Public Mini CMS base URL
`--workspace-id`	string	No*	Default workspace ID
`--project-id`	string	Recommended	Default project ID
`--collection-id`	string	No	Restrict to one collection
`--collections`	string	No	Input collections file
`--types`	string	No	Types output path
`--client`	string	No	Client output path
`--declarations`	string	No	Declarations output path

Generated Client Usage

import { createMiniCmsClient } from "./mini.client.js";

const client = createMiniCmsClient();

// Get testimonials
const response = await client.getCollectionItems("testimonials");
console.log(response.items[0]?.title);

// Or use the typed helper
const testimonials = await client.collections.testimonials.query();

Use Cases

Building a static site that fetches content at runtime
Adding CMS content to an existing web app
Type-safe content fetching in frontend code

`mini-cms list-projects`

Lists all projects in the configured workspace.

mini-cms list-projects

Basic Usage

mini-cms list-projects

Output:

Projects in workspace org_abc123:

  default (project_default_xyz789)
  website (project_website_abc123)

Options

Option	Type	Required	Description
`--base-url`	string	No*	Mini CMS base URL
`--workspace-id`	string	No*	Workspace ID
`--api-key`	string	No*	API key

Use Cases

Finding project IDs for pull/push operations
Checking which projects exist in a workspace
Automation scripts that need project information

`mini-cms project create`

Creates a new project in the workspace.

mini-cms project create --name "My Project" --slug my-project

Basic Usage

mini-cms project create \
  --name "Website" \
  --slug website

Options

Option	Type	Required	Description
`--name`	string	Yes	Project display name
`--slug`	string	Yes	URL-friendly project identifier
`--base-url`	string	No*	Mini CMS base URL
`--workspace-id`	string	No*	Workspace ID
`--api-key`	string	No*	API key

Use Cases

Creating a new project for a client site
Setting up separate projects for dev/staging/prod

`mini-cms project delete`

Deletes a project and all its collections and items.

mini-cms project delete <slug-or-id>

Basic Usage

# By slug
mini-cms project delete website

# By ID
mini-cms project delete project_website_abc123

Warning

This deletes the project and ALL collections and items within it. This action cannot be undone.

# Confirmation prompt
? Delete project "website"? This will delete all collections and items. (y/N)

Options

Option	Type	Required	Description
`<slug-or-id>`	string	Yes	Project slug or ID
`--base-url`	string	No*	Mini CMS base URL
`--workspace-id`	string	No*	Workspace ID
`--api-key`	string	No*	API key

Use Cases

Cleaning up old projects
Removing test environments

`mini-cms list-collections`

Lists collections in the workspace or project.

mini-cms list-collections

Basic Usage

# List all collections in workspace
mini-cms list-collections

# Filter by project
mini-cms list-collections --project-id project_default_xyz789

Output

Collections in workspace org_abc123:

  testimonials (col_testimonials)
    - Client quotes and endorsements
    - 2 fields: title, featured
  
  partners (col_partners)
    - Partner logos and info
    - 3 fields: name, logo, url

Options

Option	Type	Required	Description
`--base-url`	string	No*	Mini CMS base URL
`--workspace-id`	string	No*	Workspace ID
`--project-id`	string	No	Filter by project
`--api-key`	string	No*	API key

Use Cases

Viewing available collections
Finding collection IDs for scripts
Checking collection field counts

`mini-cms collection create`

Creates a new collection in a project.

mini-cms collection create --name "Testimonials" --slug testimonials

Basic Usage

# Simple collection with default text field
mini-cms collection create \
  --name "Testimonials" \
  --slug testimonials \
  --project-id project_default_xyz789

# With description and schema file
mini-cms collection create \
  --name "Testimonials" \
  --slug testimonials \
  --description "Client quotes and endorsements" \
  --schema ./testimonials-schema.json \
  --project-id project_default_xyz789

Schema File Format

[
  { "key": "title", "label": "Title", "type": "text" },
  { "key": "author", "label": "Author", "type": "text" },
  { "key": "featured", "label": "Featured", "type": "boolean" },
  { "key": "publishedAt", "label": "Published At", "type": "date" }
]

Options

Option	Type	Required	Description
`--name`	string	Yes	Collection name
`--slug`	string	Yes	URL-friendly identifier
`--description`	string	No	Collection description
`--schema`	string	No	Path to JSON schema file
`--project-id`	string	No*	Target project
`--base-url`	string	No*	Mini CMS base URL
`--workspace-id`	string	No*	Workspace ID
`--api-key`	string	No*	API key

Use Cases

Creating collections from scripts
Automation for new content types
CI/CD pipelines that set up collections

`mini-cms collection delete`

Deletes a collection and all its items.

mini-cms collection delete <slug-or-id>

Basic Usage

# By slug
mini-cms collection delete testimonials

# By ID
mini-cms collection delete col_testimonials

Warning

This deletes the collection and ALL items within it. This action cannot be undone.

? Delete collection "testimonials"? This will delete all items. (y/N)

Options

Option	Type	Required	Description
`<slug-or-id>`	string	Yes	Collection slug or ID
`--project-id`	string	No*	Project scope
`--base-url`	string	No*	Mini CMS base URL
`--workspace-id`	string	No*	Workspace ID
`--api-key`	string	No*	API key

Use Cases

Removing deprecated content types
Cleaning up test collections

`mini-cms collection item list`

Lists items in a collection.

mini-cms collection item list <slug-or-id>

Basic Usage

# List first page
mini-cms collection item list testimonials

# Paginated
mini-cms collection item list testimonials --page 2 --limit 50

Output

Items in "testimonials" (col_testimonials):

  [1] item_abc123
      title: "Great product!"
      author: "John Doe"
      featured: true
  
  [2] item_def456
      title: "Amazing service"
      author: "Jane Smith"
      featured: false

Options

Option	Type	Required	Description
`<slug-or-id>`	string	Yes	Collection slug or ID
`--page`	number	No	Page number (default: 1)
`--limit`	number	No	Items per page (default: 10)
`--project-id`	string	No*	Project scope
`--base-url`	string	No*	Mini CMS base URL
`--workspace-id`	string	No*	Workspace ID
`--api-key`	string	No*	API key

Use Cases

Inspecting collection content
Finding item IDs for updates/deletes
Debugging content issues

`mini-cms collection item insert`

Adds one or more items to a collection.

mini-cms collection item insert <slug-or-id>

Single Item with `--items`

mini-cms collection item insert testimonials \
  --items "title=Great product!;author=John Doe;featured=true"

Format: key=value;key=value where semicolons separate fields.

Single Item with `--items-file`

# Single object
mini-cms collection item insert testimonials \
  --items-file ./item.json

item.json:

{
  "title": "Great product!",
  "author": "John Doe",
  "featured": true
}

Multiple Items with `--items-file`

# Array of objects
mini-cms collection item insert testimonials \
  --items-file ./items.json

items.json:

[
  { "title": "First item", "author": "John" },
  { "title": "Second item", "author": "Jane" }
]

Stdin Input

# Pipe JSON
echo '{"title": "Piped item", "author": "Dev"}' | \
  mini-cms collection item insert testimonials

# Pipe array
cat ./items.json | mini-cms collection item insert testimonials

Auto-Generated Fields

slug: Auto-generated from title if not provided
_published: Defaults to true if not specified

Options

Option	Type	Required	Description
`<slug-or-id>`	string	Yes	Collection slug or ID
`--items`	string	No*	Item values as `key=value;key=value`
`--items-file`	string	No*	JSON file with item(s)
`--project-id`	string	No*	Project scope
`--base-url`	string	No*	Mini CMS base URL
`--workspace-id`	string	No*	Workspace ID
`--api-key`	string	No*	API key

*One of --items, --items-file, or stdin is required.

Use Cases

Seed data for new collections
Importing content from other systems
CI/CD content deployment

`mini-cms collection item update`

Updates an existing item's values.

mini-cms collection item update <slug-or-id> --id <item-id> --value "key=value"

Basic Usage

# Update single field
mini-cms collection item update testimonials \
  --id item_abc123 \
  --value "title=Updated title"

# Update multiple fields
mini-cms collection item update testimonials \
  --id item_abc123 \
  --value "title=New title;author=New Author;featured=false"

Options

Option	Type	Required	Description
`<slug-or-id>`	string	Yes	Collection slug or ID
`--id`	string	Yes	Item ID to update
`--value`	string	Yes	Updated values as `key=value;key=value`
`--project-id`	string	No*	Project scope
`--base-url`	string	No*	Mini CMS base URL
`--workspace-id`	string	No*	Workspace ID
`--api-key`	string	No*	API key

Use Cases

Editing content from CLI
Bulk updates via scripts
Fixing typos in published content

`mini-cms collection item delete`

Deletes an item from a collection.

mini-cms collection item delete <slug-or-id> --id <item-id>

Basic Usage

mini-cms collection item delete testimonials --id item_abc123

Options

Option	Type	Required	Description
`<slug-or-id>`	string	Yes	Collection slug or ID
`--id`	string	Yes	Item ID to delete
`--project-id`	string	No*	Project scope
`--base-url`	string	No*	Mini CMS base URL
`--workspace-id`	string	No*	Workspace ID
`--api-key`	string	No*	API key

Use Cases

Removing deprecated content
Cleaning up test items
Automation scripts

`mini-cms add-skill`

Installs the Mini CMS CLI skill for coding agents.

mini-cms add-skill

What It Does

Creates .opencode/skills/mini-cms-cli/SKILL.md with:

CLI command reference
Common workflows
Code examples for agent use

Output Location

.opencode/skills/mini-cms-cli/SKILL.md

mini-cms pull --project-id project_default_xyz789 --verbose

What It Shows

HTTP request headers and URLs
Response status codes
Request/response bodies
Timing information

Use Cases

Debugging API issues
Understanding request flow
Troubleshooting authentication problems

Common Workflows

New Project Setup

# 1. Initialize config
mini-cms init \
  --base-url https://mini-cms-rosy.vercel.app \
  --workspace-id org_abc123 \
  --project-id project_default_xyz789 \
  --api-key mcms_test_123

# 2. Pull existing schema
mini-cms pull --project-id project_default_xyz789

# 3. Generate browser client
mini-cms generate --project-id project_default_xyz789

Create Collection from Code

# 1. Create collection
mini-cms collection create \
  --name "Blog Posts" \
  --slug blog-posts \
  --description "Articles and blog content" \
  --schema ./blog-schema.json \
  --project-id project_default_xyz789

# 2. Pull to get the collection ID
mini-cms pull --project-id project_default_xyz789

Seed Content

# Create items from JSON file
mini-cms collection item insert testimonials \
  --items-file ./seed-data.json \
  --project-id project_default_xyz789

Sync Schema Changes

# After editing mini.collections.json locally
mini-cms push --project-id project_default_xyz789

Tips and Best Practices

Always use --project-id for pull and push to avoid ambiguity
Keep your API key secure - never commit it to version control
Use --verbose when debugging issues with the CLI
Pull before push to ensure you have the latest schema
Use stdin for automated scripts that generate content dynamically
Collection slugs must be unique within a project

Troubleshooting

"Project not found"

Verify the project ID is correct with mini-cms list-projects
Check that your API key has access to the project

"Collection not found"

Use mini-cms list-collections --project-id <id> to find the collection
Make sure you're using the correct project

"API key required"

Generate an API key from the dashboard
Pass it with --api-key or set it in mini.config.json

Authentication errors

Verify your API key is valid
Check the workspace ID matches your account
Use --verbose to see exact request/response details

CLI Guide

On this page