Installation

Prerequisites

Check these requirements before installing the SDK:

Generated types, field autocomplete, and compile-time schema checks require TypeScript. The client runs without it — see Use the SDK from JavaScript.

With TypeScript, enable strict mode in your tsconfig.json:

{
  "compilerOptions": {
    "strict": true
  }
}

Install the Packages

Add @monospace/sdk to your project, and the Monospace CLI, @monospace/cli, as a development dependency. The CLI generates the types.

npm install @monospace/sdk

pnpm add @monospace/sdk

yarn add @monospace/sdk

bun add @monospace/sdk

npm install -D @monospace/cli

pnpm add -D @monospace/cli

yarn add -D @monospace/cli

bun add -D @monospace/cli

Add the Monospace SDK to Your Project

Run sdk init to create your config file interactively.

npx @monospace/cli sdk init

pnpm exec monospace sdk init

yarn run monospace sdk init

bun run monospace sdk init

The command walks through these steps:

1. Prompt for your Monospace instance URL
2. Prompt for the workspace whose schema to read
3. Ask for an output directory (default: ./src/generated/monospace)
4. Write a monospace.config.ts file

Pass --url, --workspace, and --dir to skip the matching prompts.

Configure Your Project

The SDK generator reads your Monospace schema at build time and produces a typed TypeScript client. Regenerate the client after schema changes to keep its types in sync.

Create a monospace.config.ts (or monospace.config.js) file at your project root. It specifies your Monospace instance URL and the workspace whose schema you want to read.

The CLI loads either extension, so a .ts config works in a JavaScript project.

Remote Config

Set your Monospace instance URL and workspace identifier:

import { defineConfig } from '@monospace/sdk/config'

export default defineConfig({
  url: 'https://example.monospace.io',
  workspace: 'blog',
  output: './src/generated/monospace',
})

Local Config

Generate types from a local OpenAPI spec file instead:

import { defineConfig } from '@monospace/sdk/config'

export default defineConfig({
  input: './local-schema.json',
  output: './src/generated/monospace',
})

Config Reference

A remote config uses url and workspace; a local config uses input. Use one configuration or the other.

For a remote config, the CLI resolves the instance URL and the workspace separately, each from the first of: the --url or --workspace flag, the MONOSPACE_URL or MONOSPACE_WORKSPACE environment variable, then the config file.

The CLI rejects a config file that sets apiKey, api_key, password, secret, or token. Supply credentials as described below.

outputOptions controls the generated output:

Authenticate for Generation

Remote configs require authentication to fetch your schema. The CLI resolves credentials in this order:

1. --api-key <key> flag on the CLI command
2. MONOSPACE_API_KEY environment variable (.env files are loaded automatically)
3. OS keychain (stored via the login command)

Using an Environment Variable

Set the API key in your project's .env file:

MONOSPACE_API_KEY=your-api-key-here

Using the Login Command

Run login to authenticate with an API key or email and password:

npx @monospace/cli login

pnpm exec monospace login

yarn run monospace login

bun run monospace login

The command prompts for credentials and stores them in your OS keychain.

To remove stored credentials:

npx @monospace/cli logout

pnpm exec monospace logout

yarn run monospace logout

bun run monospace logout

Generate Types from Your Schema

Run the generator to read your schema and produce a typed client:

npx @monospace/cli sdk generate

pnpm exec monospace sdk generate

yarn run monospace sdk generate

bun run monospace sdk generate

This produces a typed client you can import:

your-project/
├── src/
│   └── generated/
│       └── monospace/
│           └── index.ts
├── monospace.config.ts
├── package.json
└── tsconfig.json

Import the client factory from the generated output. It includes your schema's types, so you do not need generic parameters:

import { createClient } from './generated/monospace';

{
  "scripts": {
    "monospace:generate": "monospace sdk generate"
  }
}

Check Your Setup

Show which instance and workspace the current directory targets, which credential the CLI uses, and who it signs you in as:

npx @monospace/cli whoami

pnpm exec monospace whoami

yarn run monospace whoami

bun run monospace whoami

When a credential is found, whoami contacts the instance to confirm the identity. Add --local to report the resolved target and credential without contacting the instance.

CLI Reference

@monospace/cli installs a binary named monospace. Call it directly inside a package.json script:

Every command also accepts --json to print a single JSON result on stdout, and --no-input to fail instead of prompting. See the CLI reference for every command, flag, and error.

Regenerate After Schema Changes

When you add, modify, or remove collections or fields in Studio, re-run the generator to keep your types in sync.

npx @monospace/cli sdk generate

pnpm exec monospace sdk generate

yarn run monospace sdk generate

bun run monospace sdk generate

The generator overwrites the output file on each run, so manual edits are lost.

Use the SDK from JavaScript

The generator emits a TypeScript file. JavaScript projects skip generation and import createClient from the package instead.

import { createClient } from '@monospace/sdk';

const client = createClient({
  url: 'https://example.monospace.io',
  workspace: 'blog',
  apiKey: 'YOUR_API_KEY',
});

const articles = await client.Articles.readMany({
  fields: ['id', 'title', 'status'],
});

Collections and methods resolve at runtime. Filters, field selection, readFirst, relational writes, and error classes behave the same as with the generated client. Autocomplete and compile-time type checks are unavailable.

Next Steps

• Client Setup — create and configure the client
• Type System — understand how schema types map to TypeScript
• CLI — every monospace command and flag
• API Overview — understand the underlying REST API