Get Started
Command-line interface for Localess — authenticate with your instance, sync translations and schemas, and generate TypeScript type definitions from your content schemas.
Package: @localess/cli
The @localess/cli package is the official command-line interface for the Localess headless CMS platform. It provides commands to authenticate with your Localess instance, synchronize translations and content schemas, and generate TypeScript type definitions from your content schemas.
The CLI is a standalone tool — framework-agnostic and independent of the SDK packages. Install it once per project (or globally) regardless of which framework you use on the application side.
Requirements
- Node.js >= 24.0.0
Installation
# Install as a project dev dependency (recommended)
npm install @localess/cli@latest -D
# Or install globally
npm install @localess/cli@latest -gFeatures
- Authentication — Secure credential storage for CLI and CI/CD environments
- Translations — Push, pull, and diff translation files against your Localess space
- Type Generation — Generate TypeScript type definitions from your Localess content schemas for end-to-end type safety
- Schema — Define content schemas in TypeScript and sync them with your space
Commands
| Command | Purpose |
|---|---|
localess login / logout | Authenticate against an instance and space |
localess translation pull|push|diff | Sync translation files |
localess type generate | Generate TypeScript definitions from the space's schemas |
localess schema validate|pull|diff|push | Sync code-defined schemas with the space |
The
translationandtypegroups were previously namedtranslationsandtypes. Both plural names still work as aliases, so existing scripts keep running.
Every command that talks to the API accepts -v, --verbose to print request URLs and statuses, and exits 1 with Not logged in when no credentials are available.
Platform Compatibility
Before a command talks to your Localess instance, the CLI reads the instance's version from <origin>/assets/version.json and stops if the two are incompatible:
- The major versions differ — the CLI and the platform must share a major version.
- The command needs a newer platform than the one it found.
The error names both versions and the matching install command, npm install --save-dev @localess/cli@<platform-major>.
The check is skipped for login, logout and schema validate, which never call the platform, and whenever no credentials are configured. If the version can't be determined within 3 seconds — for example, an instance that doesn't serve that file — the command proceeds. Set LOCALESS_SKIP_VERSION_CHECK=1 to bypass the check entirely.
Separately, after a command finishes, the CLI prints a notice when a newer @localess/cli is available.
Stored Files
| File | Description |
|---|---|
.localess/credentials.json | Stored login credentials (created by localess login) |
.localess/localess.d.ts | Generated TypeScript definitions (created by localess type generate) |
localess loginautomatically adds.localessto.gitignore(creating the file if absent).
AI Coding Agents
This package ships a SKILL.md file that provides AI coding agents (GitHub Copilot, Claude Code, Cursor, and others) with accurate, up-to-date APIs, patterns, and best practices.
Reference it from your project's AGENTS.md:
## Localess
@node_modules/@localess/cli/SKILL.md