Installation

Install

The CLI is published as @api18n/cli on npm.

npm install --save-dev @api18n/cli
# or
bun add -d @api18n/cli
# or
pnpm add -D @api18n/cli

It's a devDependency because it runs at edit time and in CI — never at runtime. Node ≥ 18 is required.

api18n init

Run from the root of your project:

npx api18n init

This creates api18n.config.ts next to your package.json. The interactive prompt asks you:

1. Where do your translation files live? Default messages/{locale}.json — the {locale} placeholder is filled with each language code at pull time (e.g. messages/en.json, messages/pt-BR.json).
2. Dashboard URL? Default https://www.api18n.com. Override if you're on a self-hosted instance.

The resulting file is plain TypeScript that exports defineConfig:

// api18n.config.ts
import { defineConfig } from '@api18n/cli';

export default defineConfig({
  locales: 'messages/{locale}.json',
});

Edit it later to add include, companyId, or typegen options — see Configuration.

api18n login

Authenticates the CLI against your api18n company.

npx api18n login

The CLI prints the dashboard URL where you'll generate a Personal Access Token (PAT) and waits for you to paste it back.

1. Open the printed URL (https://www.api18n.com/dashboard/settings/api-keys).
2. Click Create new key, give it a name like "My laptop", and pick the scopes you need:
   • translations:read — required for pull.
   • translations:propose — required for push.
   • translations:approve — reserved for future CI auto-merge; not needed for the standard flow.
3. Copy the plaintext token (a18n_live_…) — it's shown exactly once.
4. Paste it back into the CLI prompt.

Successful sign-in stores the token in ~/.api18n/credentials.json. You can verify with npx api18n whoami:

$ npx api18n whoami
✓ Signed in as eduardo@api18n.com
  Company: api18n (a4c0…f9b3)
  Host:    https://www.api18n.com

CI: skip api18n login

In CI environments, set the API18N_TOKEN environment variable instead:

API18N_TOKEN=a18n_live_… npx api18n pull

The CLI checks the environment first, then the credentials file, then the --token flag in that order.

First api18n pull

npx api18n pull

Fetches the latest dataset from the dashboard and writes one JSON file per locale plus a .d.ts for type-safe keys:

  +    messages/en.json
  +    messages/pt-BR.json
  +    messages/de.json
  +    messages/messages.d.ts

✓ Wrote 3 files.
✓ Wrote types for 42 keys (en) → messages/messages.d.ts

The .d.ts file augments the Messages interface used by @api18n/react. Add it to your tsconfig.json's include array (or just trust the auto-discovery — TypeScript picks up adjacent .d.ts files automatically in most setups).

Next steps

• Wire up the SDK: @api18n/react installation
• Browse every CLI command: Commands reference
• Tune api18n.config.ts: Configuration