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 generate TypeScript type definitions from your content schemas.

Requirements

• Node.js >= 20.0.0

Installation

# Install as a project dev dependency (recommended)
npm install @localess/cli -D

# Or install globally
npm install @localess/cli -g

Features

• 🔐 Authentication — Secure credential storage for CLI and CI/CD environments
• 🌐 Translations — Push and pull translation files to/from your Localess space
• 🛡️ Type Generation — Generate TypeScript type definitions from your Localess content schemas for end-to-end type safety

Authentication

localess login

Authenticate with your Localess instance. Credentials are validated immediately and stored securely in .localess/credentials.json with restricted file permissions (0600).

localess login --origin <origin> --space <space_id> --token <api_token>

If any option is omitted, the CLI will interactively prompt for the missing values.

Options:

Examples:

# Interactive login (prompts for any missing values)
localess login

# Non-interactive login (CI/CD)
localess login --origin https://my-localess.web.app --space MY_SPACE_ID --token MY_API_TOKEN

Authentication via Environment Variables

For CI/CD pipelines, you can provide credentials through environment variables instead of running localess login. The CLI automatically reads these variables and skips the file-based credentials:

export LOCALESS_ORIGIN=https://my-localess.web.app
export LOCALESS_SPACE=MY_SPACE_ID
export LOCALESS_TOKEN=MY_API_TOKEN

localess translations pull en --path ./public/locales/en.json

localess logout

Clear stored credentials from .localess/credentials.json.

localess logout

If you authenticated via environment variables, those must be unset manually — logout only affects file-based credentials.

Translations Management

localess translations push <locale>

Push a local JSON translation file to your Localess space. Only keys present in the file are affected, based on the selected update type.

localess translations push <locale> --path <file> [options]

Arguments:

Options:

Update Strategies:

File Formats:

• flat — A flat JSON object where keys may use dot notation:

  {
    "common.submit": "Submit",
    "nav.home": "Home"
  }

• nested — A nested JSON object that is automatically flattened before uploading:

  {
    "common": { "submit": "Submit" },
    "nav": { "home": "Home" }
  }

Examples:

# Push English translations (add missing keys only)
localess translations push en --path ./locales/en.json

# Push with update-existing strategy
localess translations push en --path ./locales/en.json --type update-existing

# Preview changes without applying (dry run)
localess translations push en --path ./locales/en.json --dry-run

# Push nested-format translations
localess translations push de --path ./locales/de.json --format nested

localess translations pull <locale>

Pull translations from your Localess space and save them to a local file.

localess translations pull <locale> --path <file> [options]

Arguments:

Options:

Examples:

# Pull English translations as flat JSON
localess translations pull en --path ./locales/en.json

# Pull German translations as nested JSON
localess translations pull de --path ./locales/de.json --format nested

TypeScript Type Generation

localess types generate

Fetch your space's OpenAPI schema from Localess and generate TypeScript type definitions. The output file provides full type safety when working with Localess content in your TypeScript projects.

localess types generate [--path <output_path>]

Options:

Note: Your API token must have Development Tools permission enabled in Localess Space settings.

Example:

# Generate types to the default location
localess types generate

# Generate types to a custom path
localess types generate --path src/types/localess.d.ts

Using generated types:

import type { Page, HeroBlock } from './.localess/localess';
import { getLocalessClient } from "@localess/react";

const client = getLocalessClient();
const content = await client.getContentBySlug<Page>('home', { locale: 'en' });
// content.data is now fully typed as Page

Stored Files

It is recommended to add .localess/credentials.json to your .gitignore to avoid committing sensitive credentials.

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. Most agents automatically read SKILL.md when starting a session.

Using SKILL.md in your project

SKILL.md is included in the npm package, so it is available locally after installation. Reference it from your project's AGENTS.md to ensure your agent reads accurate Localess documentation every session:

## Localess

@node_modules/@localess/cli/SKILL.md

The @ prefix is the syntax used by most agent tools (GitHub Copilot, Claude Code, Cursor) to import file contents inline into the agent context.

When you change the public API of this package, update SKILL.md alongside your code:

• New option or parameter → add it to the relevant options table and usage example
• Changed behaviour → update the description and any affected code snippets
• Deprecated API → mark it clearly and point to the replacement
• New command or subcommand → add a full entry with all flags and examples

License

MIT