> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mdcms.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Install MDCMS packages and start managing content in your project

Get MDCMS running in your own application. This guide assumes you have an MDCMS server available (self-hosted or managed).

<Tip>
  Need to set up your own server first? Follow the [Self-Hosting
  guide](/guide/self-hosting) to get MDCMS running with Docker Compose, then
  come back here.
</Tip>

<Note>
  Looking to contribute to MDCMS itself? See [Development
  Setup](/development/setup).
</Note>

<Tip>
  **Using an AI coding agent?** `npx skills add mdcms-ai/mdcms/skills` installs
  the [MDCMS Skills Pack](/agent-skills) so your agent can walk through this
  quickstart for you.
</Tip>

## 1. Install the CLI

<CodeGroup>
  ```bash npm theme={null}
  npm install --save-dev @mdcms/cli
  ```

  ```bash bun theme={null}
  bun add -D @mdcms/cli
  ```
</CodeGroup>

## 2. Initialize your project

The `mdcms init` wizard configures everything — server connection, project/environment selection, content type detection, and initial sync:

```bash theme={null}
npx mdcms init
```

It will:

* Ask for your MDCMS server URL
* Open a browser for authentication
* Scan your repo for existing Markdown/MDX files
* Generate a `mdcms.config.ts` with inferred content types
* Push the initial schema and content to the server

See [CLI Installation](/guide/cli/installation) for details on the init wizard.

## 3. Define your content schema

The generated `mdcms.config.ts` is your starting point. Customize it to match your content model:

```typescript mdcms.config.ts theme={null}
import { defineConfig, defineType, fieldTypes } from "@mdcms/cli";
import { z } from "zod";

const Author = defineType("Author", {
  directory: "content/authors",
  fields: {
    name: z.string().min(1),
    bio: z.string().optional(),
  },
});

const BlogPost = defineType("BlogPost", {
  directory: "content/blog",
  localized: true,
  fields: {
    title: z.string().min(1),
    author: fieldTypes.reference("Author"),
    tags: z.array(z.string()),
  },
});

export default defineConfig({
  project: "my-site",
  environment: "production",
  serverUrl: "https://your-mdcms-server.example.com",
  contentDirectories: ["content"],
  locales: {
    default: "en",
    supported: ["en", "fr"],
  },
  types: [Author, BlogPost],
});
```

See the [Schema Guide](/guide/schema/defining-types) for field types, references, and environment overlays.

## 4. Sync schema and content

```bash theme={null}
# Push your schema to the server
npx mdcms push

# Pull content from the server to local Markdown files
npx mdcms pull

# Edit .md or .mdx files with any tool, then push changes back
npx mdcms push
```

See the [CLI Commands](/guide/cli/commands) reference for all available flags.

## 5. Fetch content in your app

Install the SDK:

<CodeGroup>
  ```bash npm theme={null}
  npm install @mdcms/sdk
  ```

  ```bash bun theme={null}
  bun add @mdcms/sdk
  ```
</CodeGroup>

Query content in your application:

```typescript theme={null}
import { createClient } from "@mdcms/sdk";

const cms = createClient({
  serverUrl: "https://your-mdcms-server.example.com",
  apiKey: process.env.MDCMS_API_KEY!,
  project: "my-site",
  environment: "production",
});

// List published blog posts
const { data: posts } = await cms.list("BlogPost", {
  locale: "en",
  published: true,
  limit: 10,
});

// Fetch a single post with resolved references
const post = await cms.get("BlogPost", {
  slug: "hello-world",
  resolve: ["author"],
});
```

See the [SDK reference](/api-reference/sdk) for the full API.

## 6. Embed the Studio UI (optional)

Add a visual editing interface to your app by installing `@mdcms/studio` and mounting it on a catch-all route:

```tsx app/admin/[[...path]]/page.tsx theme={null}
import { createStudioEmbedConfig } from "@mdcms/studio/runtime";
import config from "../../../mdcms.config";
import { AdminStudioClient } from "./admin-studio-client";

export default async function AdminPage() {
  return <AdminStudioClient config={createStudioEmbedConfig(config)} />;
}
```

For the full setup — including MDX component registration, authentication, CORS configuration, and production hardening — see the [Integration Guide](/guide/integration).

## Next steps

<CardGroup cols={2}>
  <Card title="CLI Commands" icon="terminal" href="/guide/cli/commands">
    Push, pull, login, schema sync, and all CLI flags
  </Card>

  <Card title="Schema Guide" icon="file-code" href="/guide/schema/defining-types">
    Field types, references, environment overlays, MDX components
  </Card>

  <Card title="Studio Guide" icon="layout-dashboard" href="/guide/studio/dashboard">
    Visual content editing, publishing, and version history
  </Card>

  <Card title="SDK Reference" icon="plug" href="/api-reference/sdk">
    Full typed client API for content reads
  </Card>
</CardGroup>