@monospace/cli

Command line tool for Monospace. It handles instance sign-in and generates TypeScript types for @monospace/sdk. It scaffolds and builds data connector extensions.

Quick start

Install the CLI as a dev dependency of your project.

npm install --save-dev @monospace/cli

With pnpm, Yarn, or Bun, use pnpm add -D, yarn add -D, or bun add -D.

npx @monospace/cli sdk init      # writes monospace.config.ts
npx @monospace/cli login         # stores a credential for the configured instance
npx @monospace/cli sdk generate  # writes index.ts to the configured output directory

sdk init asks for your instance URL and workspace. It asks for an output directory with ./src/generated/monospace as the suggested path. login asks whether to use an API key or your email and password.

Running the CLI

The package installs a monospace binary. Run it through your package manager.

| Package manager | Installed in the project | Not installed | | --- | --- | --- | | npm | npx @monospace/cli | npx @monospace/cli | | pnpm | pnpm exec monospace | pnpm dlx @monospace/cli | | Yarn | yarn monospace | yarn dlx @monospace/cli (Yarn 2 or later) | | Bun | bun run monospace | bunx @monospace/cli |

Use the package name @monospace/cli with npx and bunx. An unrelated package named monospace exists on npm, and they fetch it when the CLI is not installed in the project.

A project-local install keeps the CLI in the same lockfile as @monospace/sdk and @monospace/extension-kit. The generated types and extension builds depend on those packages' versions. The examples below use npx @monospace/cli. Every command accepts --help.

Commands

| Command | Description | | --- | --- | | monospace login | Store a credential for an instance. | | monospace logout | Remove a stored credential. A stored session is revoked first. | | monospace whoami | Show the targeted instance and workspace, and which credential the CLI uses. | | monospace sdk init | Create a monospace.config.ts for type generation. | | monospace sdk generate | Generate TypeScript types from a workspace schema. | | monospace extension create | Scaffold a data connector project. | | monospace extension build | Bundle an extension and optionally install it into an instance. |

Signing in

npx @monospace/cli login --url https://example.monospace.io

login stores the credential in the operating system keyring, keyed by instance URL. It never writes credentials to project files. Signing in again replaces the stored credential for that instance.

To store an API key without a terminal, pipe it to standard input.

echo "$MONOSPACE_KEY" | npx @monospace/cli login --url https://example.monospace.io --api-key-stdin

In CI, skip login and set MONOSPACE_API_KEY. Commands that call an instance use the first credential they find, in this order.

1. The --api-key flag, accepted by whoami and sdk generate
2. The MONOSPACE_API_KEY environment variable
3. The credential stored by login

Run whoami to check which instance a directory targets and which credential the CLI uses. whoami --local reports the same without contacting the instance.

Choosing the instance and workspace

Commands resolve the instance URL and, where they take --workspace, the workspace from the first of these sources.

1. The --url and --workspace flags
2. The MONOSPACE_URL and MONOSPACE_WORKSPACE environment variables
3. url and workspace in monospace.config.ts or monospace.config.js in the working directory

The CLI does not search parent directories for the config file. It loads a .env file from the working directory before it runs, and variables already set in the environment take precedence over the file.

Generating SDK types

sdk generate reads the workspace's OpenAPI schema and writes index.ts to the config's output directory, replacing it on each run. Run it again when your schema changes. The credential needs the openApiSchema:read entitlement.

--url and --workspace override the config for one run, and --config <path> selects a different config file.

To generate from an OpenAPI JSON document exported from an instance, set input in the config. No credential is needed.

// monospace.config.ts
import type { MonospaceConfig } from '@monospace/sdk/config';

export default {
	input: './openapi.json',
	output: './src/generated/monospace',
} satisfies MonospaceConfig;

Relative input and output paths resolve against the working directory. See the @monospace/sdk README for using the generated client.

Building data connectors

Data connectors let Monospace read from and write to services it has no built-in support for. You write them with @monospace/extension-kit. The extension commands do not contact an instance and need no sign-in.

Create a project

npx @monospace/cli extension create ./acme-store --id acme/store --name "Acme Store"

Without --id and --name, create asks for them. The id has the form namespace/name. The directory must not exist or must be empty apart from .git.

The project contains a connector that returns sample items for one collection. It includes extension.config.json and scripts for build and typecheck. It lists @monospace/cli, rolldown, and typescript as dev dependencies. create leaves dependency installation to you and prints the install and build commands for the package manager it detects.

Build

Run the build from the project root.

npm run build

The build script runs monospace extension build. It reads extension.config.json and writes one bundled JavaScript module per entry and a manifest.json to ./dist, or to the directory given by --out-dir. Bundling uses the rolldown installed in the project, which must satisfy ^1.2.0. The build does not check types, so run the typecheck script as well.

Install into an instance

Pass the instance's extension directory to --install-to. The instance reads extensions from ./extensions relative to its working directory unless MONOSPACE_EXTENSIONS__INSTALL_LOCATION is set.

npm run build -- --install-to ../monospace/extensions

The CLI copies the build into a subdirectory named after the extension id, with / replaced by __, and replaces that subdirectory on each install. A build that fails leaves the installed copy in place.

Add --watch to rebuild when a source file or extension.config.json changes. Stop it with Ctrl-C. An instance loads extensions when it starts. Start it with MONOSPACE_EXTENSIONS__AUTO_RELOAD=true to reload an extension each time an install replaces it.

npm run build -- --watch --install-to ../monospace/extensions

Network permissions and the other extension.config.json fields are covered in the @monospace/extension-kit README and the extension config reference.

Scripting

--no-input turns prompts off. If required input is missing, the command reports an error naming the flag to supply. Prompts are also off when stdin or stderr is not a terminal, or when CI is set to anything other than 0 or false. sdk init --yes replaces an existing config file without asking.

--json prints one JSON object to stdout when the command finishes, including when it fails. Prompts, notes, and errors go to stderr. --json does not turn prompts off, so pass --no-input as well in scripts.

{
	"schema": "monospace.sdk.generate/1",
	"outcome": "failed",
	"effectState": "none",
	"data": null,
	"error": {
		"category": "configuration",
		"code": "sdk.config_not_found",
		"message": "Config file not found. Searched: monospace.config.ts, monospace.config.js",
		"fix": "Run `monospace sdk init` to create one."
	}
}

The process exits with 1 when outcome is failed and 0 when it is ok or cancelled. See Read JSON Output for each command's data fields.

Documentation

• CLI reference: every flag, environment variable, JSON result, and exit code
• SDK Quickstart
• SDK Installation

Requirements

• Node.js 22.12 or newer
• An operating system keyring for login. Where none is available, such as on a server without a secret service, set MONOSPACE_API_KEY instead.

Feedback

Open an issue to report a bug or suggest a change.

License

MIT