Skip to main content
STRINGTIDE

CLI reference

Same text as stringtide help. When the binary changes, this page changes with it.

Commands

account

login                    Sign in with a device code
logout                   Forget the stored token
whoami                   Who you are, which org, which plan
org list                 Organisations you belong to
org switch <slug>        Change the active organisation

project

init                     Detect the layout and write stringtide.json
projects list            Projects in the active organisation
projects create          Create one from this directory (preferred)
link <project-slug>      Point this directory at a project
locales list             Languages this project is translated into
locales add <code…>      Start a language (it appears at 0%)
locales remove <code…>   Stop targeting a language

the loop

status                   What's translated and what isn't
push                     Send source strings
translate --locale fr    Push, translate gaps, write validated files
pull                     Write approved translations and new source strings into your files
export --locale fr       Take the translations out

other ways in

upload <path...>         Import a zip, a folder, or loose files

Global options

--cwd <path>        Project directory (default: the current one)
--json              Machine-readable output, stable shape
--no-input          Never prompt; fail with instructions instead
--token <token>     Override the stored credentials
--api <url>         Override the API URL
--project <slug>    Override the linked project
--version           Print the version

stringtide init

--source-locale <code>   The language the project is written in
--dry-run                Print what would be written, write nothing

stringtide status

--check             Exit non-zero when translations are missing (the CI gate)
--strict            Also fail when the source language was only guessed
--source-locale <code>   Override the source language for every set

stringtide push

--dry-run           Show what would be sent, send nothing

stringtide translate

--locale <code>     Target language (required unless --all)
--all               Every targetLocale in stringtide.json / the project
--dry-run           Count missing keys and words, spend nothing (--all uses local config).
                    Signed in, also checks this month's allowance and memory hits
--offline           With --dry-run: count from the files only, no network
--review            Suggestions only — approve in the console, then pull
--force             On write, overwrite a conflict. Never a validation failure.

stringtide pull

--locale <code>     Only this language
--force             Overwrite a conflict. Never a validation failure.
--dry-run           Print the exact patch, write nothing

stringtide projects create

--slug <slug>       Default: this directory's name
--name <name>
--source-locale <code>
--from-config       Take the source language from stringtide.json

stringtide upload

<path...>           Zips, folders and loose files. Zips are read in place.
--source-locale <code>   The language the files are written in
--dry-run           Show what would be imported, send nothing

stringtide export

--locale <code>     Only this language
--format <fmt>      json (default), csv, xlf
--out <dir>         Default: ./export
--include-drafts    Include translations nobody has approved

Usage and setup

usage

stringtide <command> [options]

configuration, most specific first

flags → env (STRINGTIDE_TOKEN, STRINGTIDE_PROJECT, STRINGTIDE_API)
      → .stringtide/project → ~/.stringtide/credentials

stringtide.json is committed — it is the team's copy of the layout,
including targetLocales so `status --check` can see a declared language
with no files yet. .stringtide/ is gitignored. Credentials live in
~/.stringtide/, mode 0600.

offline

init and status read the filesystem and never touch the network.
translate --dry-run does too when signed out, or with --offline; signed in,
it asks the server about your allowance and falls back quietly if it can't.
Live translate requires an account.

more

stringtide help patterns
stringtide help exit-codes

Path patterns

Path patterns

A pattern says where translation files live, relative to a directory. Two
tokens are understood:

  {locale}     the language code — required unless one file holds every language
  {namespace}  a bundle name, when a locale is split across files

  {locale}.json                 messages/en.json
  {locale}/{namespace}.json     locales/en/common.json
  {namespace}/{locale}.json     i18n/common/en.json
  {namespace}.{locale}.json     copy/common.en.json
  active.{locale}.json          go-i18n
  app_{locale}.arb              Flutter
  translations.json             one file holding every language

Detection handles the common layouts on its own. Write a pattern when it
can't — anything expressible above needs no code change:

  {
    "sets": [{ "dir": "./i18n", "pattern": "{namespace}/{locale}.json" }],
    "sourceLocale": "de",
    "targetLocales": ["fr", "es"]
  }

Exit codes

Exit codes

  0   success
  1   generic error, or --check found missing translations
  2   conflicts left unapplied
  3   auth or scope problem
  4   plan limit reached

Every failure also prints a stable error code (E_AUTH, E_SCOPE, E_CONFLICT,
E_LIMIT, E_PATTERN_NO_MATCH, E_NO_SETS, E_NO_SOURCE_LOCALE, E_NETWORK,
E_RATE_LIMIT) in both text and --json output. A server-side failure (E_INTERNAL)
also prints a request id to quote when reporting it.