Commands

Every api18n CLI command, its flags, and example output.

The CLI exposes nine commands. All commands read api18n.config.ts from the current working directory and resolve the auth token from (in order) the --token flag, the API18N_TOKEN env var, then ~/.api18n/credentials.json.

`init`

Bootstrap a new project with an api18n.config.ts.

npx api18n init

Interactive prompts for the locale path pattern and the dashboard URL. Writes api18n.config.ts next to package.json and adds messages/ to .gitignore if it isn't already tracked (with a confirmation prompt).

`login`

Store a Personal Access Token for future commands.

npx api18n login [--base-url <url>] [--token <token>]

Flag	Purpose
`--base-url`	Override the dashboard URL (for self-hosted instances).
`--token`	Pass the token non-interactively. Skip the prompt.

Without flags the CLI prints the URL where you'll mint a PAT and waits for you to paste it. Token is stored in ~/.api18n/credentials.json.

`logout`

Delete the locally stored token.

npx api18n logout

Doesn't revoke the token server-side — use the dashboard's API Keys page to revoke. logout only removes the local file.

`whoami`

Show the signed-in user, company, and host.

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

Useful for verifying that a CI token resolves to the company you expect.

`pull`

Fetch translations from the dashboard and write them to local files.

npx api18n pull [--dry-run] [--locale <codes...>]

Flag	Purpose
`--dry-run`	Show what would change without writing files or types.
`--locale`	Restrict to specific locale codes (space-separated): `--locale en pt`

Example:

$ npx api18n pull

  +    messages/en.json
  +    messages/pt-BR.json
  ~    messages/de.json

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

Symbols: + = created, ~ = updated, = = unchanged. Empty translations (null values) are omitted from the JSON so missing keys don't appear as JSON nulls.

The companion messages.d.ts is written if typegen is enabled in api18n.config.ts (it is by default).

`push`

Submit local edits as a proposal for dashboard review.

npx api18n push [--dry-run] [--message "<text>"]

Flag	Purpose
`--dry-run`	Print the diff without submitting.
`-m`, `--message`	Attach a summary shown in the dashboard review card.

The CLI diffs every local file against the server dataset and groups the changes into create / update / delete operations. Submitting opens a proposal — the dashboard admin sees:

$ npx api18n push -m "Refresh onboarding copy"

   +  3 create   onboarding.welcome, onboarding.cta, onboarding.disclaimer
   ~  7 update   button.cancel, button.save, header.title, +4 more
   -  1 delete   legacy.deprecated

✓ Proposal #42 opened for review.
  → https://www.api18n.com/dashboard/translation

Until the proposal is approved or rejected, the local files don't differ from what the server thinks. Re-running push on the same diff returns the same proposal id (idempotent).

`status`

Show pending proposals and local-vs-server drift.

$ npx api18n status

Pending proposals (1)
  #42  eduardo@api18n.com · 12m ago · "Refresh onboarding copy"
       3 create, 7 update, 1 delete

Local drift
  ~ messages/en.json  (2 keys changed since pull)

Run `api18n pull` to sync the server changes, or `api18n push` to submit
your local edits as a new proposal.

Read-only — doesn't pull, push, or alter anything.

`proposals list`

List recent proposals (any status).

npx api18n proposals list [--status <status>] [--limit <n>]

Flag	Purpose
`--status`	Filter: `pending`, `approved`, `rejected`, or `superseded`.
`--limit`	Maximum rows to show (default: 20).

Example:

$ npx api18n proposals list --status pending --limit 5

ID    Author                    When        Counts          Summary
#42   eduardo@api18n.com        12m ago     3c · 7u · 1d    Refresh onboarding copy
#39   ci-deploy                 1h ago      0c · 2u · 0d    Auto-sync from /messages

`proposals show <id>`

Print the full diff of a single proposal.

npx api18n proposals show 42 [--json]

By default prints a human-readable diff. With --json outputs the raw proposal record (suitable for piping into jq).

$ npx api18n proposals show 42

Proposal #42 (pending) — Refresh onboarding copy
Opened by eduardo@api18n.com, 12m ago

Create (3)
  + onboarding.welcome    en: "Welcome to api18n"  pt: "Bem-vindo ao api18n"
  + onboarding.cta        en: "Start free trial"   pt: "Começar teste grátis"
  + onboarding.disclaimer en: "No credit card …"   pt: "Sem cartão de crédito…"

Update (7)
  ~ button.cancel
      en: "Cancel"        → "Cancel order"
  ~ button.save
      en: "Save"          → "Save changes"
  …

Delete (1)
  - legacy.deprecated

`types`

Regenerate messages.d.ts without running a full pull.

npx api18n types

Hits /api/cli/dataset to get the latest key list and writes the type declarations to the path configured in typegen.out (default messages/messages.d.ts). Useful if you've added scopes that can read but not propose, or you just want fresh types in CI.

PreviousWelcome NextConfiguration