CLI Commands

The Stringhive CLI has three core commands (push, pull, audit) plus two utility commands (hives, locales). All commands read the same config file.

stringhive push

Reads your local translation files and pushes source strings to Stringhive.

npx stringhive push [hive]

The hive argument is optional when hive is set in your config file.

Options

Examples

# Push source strings
stringhive push my-app

# Push source strings and seed all local translations too
stringhive push my-app --with-translations

# Keep the hive in sync — removes strings deleted from your files
stringhive push my-app --sync

# Wipe translations whenever a source string changes
stringhive push my-app --conflict-strategy clear

# Skip specific files
stringhive push my-app --exclude en.json

# Only push specific files
stringhive push my-app --include fr.json --include de.json

stringhive pull

Downloads translations from Stringhive and writes them to your lang directory. The source locale is skipped by default.

npx stringhive pull [hive]

Options

Examples

# Pull all translated locales
stringhive pull my-app

# Pull just French and German
stringhive pull my-app --locale fr de

# Pull everything, including the source locale
stringhive pull my-app --include-source

# Preview before writing anything
stringhive pull my-app --dry-run

Output:

Pulling 3 locale(s) from hive 'my-app'...
  ✓ fr: 1245 keys → ./lang/fr.json
  ✓ de: 1240 keys → ./lang/de.json
  ✓ es: 1198 keys → ./lang/es.json
✓ Done. 3683 total keys written across 3 locale(s).

stringhive audit

Compares the keys in your local source locale file against the keys stored in Stringhive and reports the diff. Optionally checks translation approval coverage. Nothing is written or changed.

npx stringhive audit [hive]

Options

Examples

# Audit key parity
stringhive audit my-app

# Fail CI if keys are out of sync
stringhive audit my-app --fail-on-missing --fail-on-orphaned

# Machine-readable output
stringhive audit my-app --format json

# Fail CI if any locale has unapproved translations
stringhive audit my-app --fail-on-unapproved

# Only check specific locales
stringhive audit my-app --fail-on-unapproved --locale fr,de,es

# Allow up to 5% unapproved — useful mid-release when some strings are still in review
stringhive audit my-app --fail-on-unapproved --min-approved 95 --locale fr,de

Text output:

Audit: my-app
  Local keys:      1245
  Stringhive keys: 1248

✗ Unpushed (2) — local but not in Stringhive:
    auth.new_feature
    settings.beta_opt_in

✗ Orphaned (3) — in Stringhive but not in local file:
    deprecated.old_key
    legacy.signup_v1
    legacy.signup_v2

JSON output:

{
  "hive": "my-app",
  "local_key_count": 1245,
  "api_key_count": 1248,
  "unpushed": ["auth.new_feature", "settings.beta_opt_in"],
  "orphaned": ["deprecated.old_key", "legacy.signup_v1", "legacy.signup_v2"],
  "unapproved": {
    "fr": { "approved": 1100, "total": 1245, "approved_percent": 88.4 },
    "de": { "approved": 1200, "total": 1245, "approved_percent": 96.4 }
  }
}

Static analysis with --scan-source

Pass a glob to also scan your source code for translation key references. The command looks for t('key'), $t('key'), and i18n.t('key') calls — covering Vue, React, and plain JS/TS.

stringhive audit my-app --scan-source 'src/**/*.{js,ts,vue}'

This adds two more sections to the report:

• Undefined — keys called in source code that don't exist in your local JSON (runtime translation misses)
• Unused — keys defined in your local JSON that are never called in source code (dead strings)

{
  "hive": "my-app",
  "local_key_count": 1245,
  "api_key_count": 1248,
  "unpushed": [],
  "orphaned": [],
  "scan": {
    "source_key_count": 1239,
    "undefined": ["checkout.promo_banner"],
    "unused": ["onboarding.legacy_step3", "onboarding.legacy_step4"]
  }
}

stringhive hives

List all hives your token can see:

npx stringhive hives

stringhive locales

List available locales for a hive:

npx stringhive locales <hive>

Using in package.json scripts

Add these to your package.json so you don't have to remember the flags:

{
  "scripts": {
    "i18n:push": "stringhive push",
    "i18n:pull": "stringhive pull",
    "i18n:sync": "stringhive push --sync && stringhive pull",
    "i18n:audit": "stringhive audit --fail-on-missing --fail-on-orphaned",
    "i18n:check-approvals": "stringhive audit --fail-on-unapproved --locale fr,de,es"
  }
}

CI/CD usage

# Push source strings on merge
- run: npx stringhive push --conflict-strategy keep

# Audit key parity
- run: npx stringhive audit --fail-on-missing

# Pull translations before build
- run: npx stringhive pull

To gate a release on translation approval, add an unapproved check on your release or deploy branch:

# Block the deploy if launch locales aren't fully approved
- run: npx stringhive audit my-app --fail-on-unapproved --locale fr,de,es

Use a token scoped to Write for push and Read for pull. Audit only needs Read.