Globalize CLI Usage

This skill guides you through managing translation resources on the Globalize platform using the CLI (globalise-now-cli).

Always use --json when running commands programmatically. Parse JSON output to extract IDs for subsequent commands. Many operations require UUIDs returned from prior steps.

All examples use npx @globalize-now/cli-client. If the CLI is installed globally, replace with globalise-now-cli.

Step 1: Prerequisite Check

Verify authentication is configured:

npx @globalize-now/cli-client auth status --json

If this fails or reports no credentials, run the globalize-now-account-setup skill first.

Step 2: Common Workflow — Create a Project and Connect a Repository

This is the most common end-to-end workflow. Follow these sub-steps in order:

2a. Fetch and match available languages

Projects must be created using language IDs returned from the languages API. Before creating a project, fetch the catalog and match the user's desired languages against it.

1. Fetch the language catalog:

npx @globalize-now/cli-client languages list --json

This returns an array of language objects, each with id (UUID), name, and locale (BCP 47 code).

1. Match desired languages against the catalog. Compare the user's source and target locale codes (e.g., en, fr, de, ja) against the locale field in the returned list. Extract the corresponding id for each match.

1. Report unsupported languages. If any of the user's desired languages do not appear in the catalog, inform the user which languages are unsupported and cannot be added to the project. Do not silently skip them — the user must acknowledge the gap before proceeding. Only continue with languages that have a matching catalog entry.

2b. Create a project

Use the language IDs (UUIDs) matched in step 2a — not bare locale codes:

npx @globalize-now/cli-client projects create \
  --name "My App" \
  --source-language <SOURCE_LANGUAGE_ID> \
  --target-languages <TARGET_LANGUAGE_ID_1> <TARGET_LANGUAGE_ID_2> \
  --json

--target-languages accepts space-separated or comma-separated values.

Parse the returned JSON to extract the project ID.

2c. Connect the repository

Globalize uses a GitHub App or GitLab OAuth connection to access repository contents. Follow these sub-steps in order.

1. Get the git remote URL:

git remote get-url origin

If the command fails (no remote named origin), STOP. Tell the user: "No git remote origin found. Please add a remote (git remote add origin <URL>) and try again, or provide the git URL manually." If the user provides a URL manually, use that URL and continue.

2. Parse the URL — extract owner and repo/project:

• GitHub HTTPS: https://github.com/<OWNER>/<REPO>.git
• GitHub SSH: [email protected]:<OWNER>/<REPO>.git
• GitLab HTTPS: https://gitlab.com/<OWNER>/<PROJECT>.git
• GitLab SSH: [email protected]:<OWNER>/<PROJECT>.git

Store the URL as <GIT_URL>. Important: The CLI only accepts HTTPS URLs for --git-url. If the remote is an SSH URL, convert it to HTTPS format.

• If the URL contains github.com: proceed with the GitHub flow (sub-step 3 onward).
• If the URL contains gitlab.com: proceed with the GitLab flow (below).
• Otherwise: STOP. Tell the user: "Globalize supports GitHub and GitLab repositories. The detected remote URL (<URL>) does not appear to be either." Do NOT proceed.

3. CONSENT GATE — Confirm repository details with the user. You MUST complete this step before proceeding.

Present the detection result and ask the user to confirm:

I detected the following repository:
- Git URL: <GIT_URL>
- Owner: <OWNER>
- Repo: <REPO>

I'll connect this repository to your Globalize project using the GitHub App (or GitLab OAuth). This may open a browser window for you to approve the installation. Is this correct?

Wait for the user's response before proceeding.

• User confirms → continue to sub-step 4 (GitHub) or the GitLab flow.
• User corrects the URL → re-parse the corrected URL from sub-step 2.

GitHub Flow

4. Set up the GitHub App and connect the repository:

4a. Check for existing GitHub App installations:

npx @globalize-now/cli-client github installations --json

This returns an array of installations. Each has id (a UUID — Globalize's internal installation record), installationId (the numeric GitHub installation ID, e.g. 122432012), accountLogin (the GitHub org or user name), and accountType.

4b. Match installation to repo owner:

Look for an installation whose accountLogin matches <OWNER> (case-insensitive). Capture both IDs: the numeric installationId as <GITHUBINSTALLATIONID> (for github repos/branches/detect --installation-id) and the UUID id as <INSTALLATION_UUID> (for repositories create --github-installation-id).

• Match found → capture both IDs, skip to sub-step 4d.
• No match → proceed to sub-step 4c.

4c. Install the GitHub App (requires user interaction):

npx @globalize-now/cli-client github install --no-wait --json

This returns { "installUrl": "...", "nonce": "..." } immediately. Present the installUrl to the user and ask them to open it in their browser, select the correct GitHub account/org, and approve the installation.

After the user confirms they have completed the browser flow, check the status:

npx @globalize-now/cli-client github install-status --nonce <NONCE> --json

This returns { "status": "completed", "installationId": "...", "accountLogin": "..." } when done, { "status": "pending" } if the user hasn't finished yet, or { "status": "expired" } if the nonce expired. Check status === "completed". If not completed, ask the user to confirm they finished and retry.

After completion, run github installations --json again to find <GITHUBINSTALLATIONID> (numeric installationId) and <INSTALLATION_UUID> (UUID id) for the target owner.

4d. Verify repo access:

npx @globalize-now/cli-client github repos --installation-id <GITHUB_INSTALLATION_ID> --json

Confirm that <OWNER>/<REPO> appears in the returned list. If not, the GitHub App may not have access to this specific repository — inform the user they need to adjust the installation's repository access settings on GitHub.

4e. Connect the repository:

npx @globalize-now/cli-client repositories create \
  --project-id <PROJECT_ID> \
  --git-url <GIT_URL> \
  --provider github \
  --github-installation-id <INSTALLATION_UUID> \
  --json

Optional flags: --branches <branches...>, --patterns '<JSON array>', --import-mode <ignore|reviewed|translated>, --import-scope <newkeysonly|all_keys>.

Parse the returned JSON to extract the repository ID.

GitLab Flow

For GitLab repositories:

4a. Check for existing GitLab connections:

npx @globalize-now/cli-client gitlab connections --json

This returns an array of connections. Each has id (UUID), username, gitlabUserId, status, and createdAt.

4b. Match connection to repo owner:

Look for a connection whose username matches the GitLab owner (case-insensitive). If found, use its id as <CONNECTION_ID>.

• Match found → use its id as <CONNECTION_ID>, skip to sub-step 4d.
• No match → proceed to sub-step 4c.

4c. Install the GitLab OAuth connection (requires user interaction):

npx @globalize-now/cli-client gitlab install --no-wait --json

This returns { "installUrl": "...", "nonce": "..." } immediately. Present the installUrl to the user and ask them to open it in their browser and authorize the GitLab connection.

After the user confirms they have completed the browser flow, check the status:

npx @globalize-now/cli-client gitlab install-status --nonce <NONCE> --json

This returns { "status": "completed", "connectionId": "...", "username": "..." } when done, { "status": "pending" } if the user hasn't finished yet, or { "status": "expired" } if the nonce expired. Check status === "completed". If not completed, ask the user to confirm they finished and retry.

Once completed, use connectionId as <CONNECTION_ID>.

4d. List GitLab projects and verify access:

npx @globalize-now/cli-client gitlab projects --connection-id <CONNECTION_ID> --json

Match pathWithNamespace against <OWNER>/<PROJECT>. If not found, the GitLab connection may not have access to this project — inform the user.

4e. Connect the repository:

npx @globalize-now/cli-client repositories create \
  --project-id <PROJECT_ID> \
  --git-url <GIT_URL> \
  --provider gitlab \
  --gitlab-connection-id <CONNECTION_ID> \
  --json

Optional flags: --branches <branches...>, --patterns '<JSON array>', --import-mode <ignore|reviewed|translated>, --import-scope <newkeysonly|all_keys>.

Parse the returned JSON to extract the repository ID.

2d. Detect repository configuration

For GitHub repos, you can detect i18n structure via the GitHub App:

npx @globalize-now/cli-client github detect \
  --installation-id <GITHUB_INSTALLATION_ID> \
  --owner <OWNER> \
  --repo <REPO> \
  --json

For GitLab repos, you can detect i18n structure via the GitLab connection:

npx @globalize-now/cli-client gitlab detect \
  --connection-id <CONNECTION_ID> \
  --project-id <GITLAB_PROJECT_ID> \
  --json

Alternatively (or additionally), auto-discover from the connected repository:

npx @globalize-now/cli-client repositories detect \
  --id <REPO_ID> \
  --json

Note: All detection commands run against remote code, not the local working copy. If the user has uncommitted or unpushed changes that affect locale files, detection will not reflect those changes. Inform the user if this applies.

Step 2.5: Project Configuration

Projects have a typed config object for QA, provider, VCS, and notification settings. Use projects update with --config to set or change configuration.

Reading current config

npx @globalize-now/cli-client projects get --id <PROJECT_ID> --json

The returned JSON includes a config object with the current settings.

Updating config

Pass a JSON object via --config. The object is merged — only include the keys you want to change:

npx @globalize-now/cli-client projects update \
  --id <PROJECT_ID> \
  --config '{"qa": {"enabledChecks": ["placeholder", "terminology"]}}' \
  --json

You can also update --name, --source-language, and --target-languages in the same call.

Config sections

Examples

Enable QA checks:

npx @globalize-now/cli-client projects update \
  --id <PROJECT_ID> \
  --config '{"qa": {"enabledChecks": ["placeholder", "length", "terminology", "formatting"], "aiReviewScope": "enabled"}}' \
  --json

Configure GitHub PR translations:

npx @globalize-now/cli-client projects update \
  --id <PROJECT_ID> \
  --config '{"github": {"prTranslations": true, "ignoreDraftPrs": true}}' \
  --json

Set up webhook notifications:

npx @globalize-now/cli-client projects update \
  --id <PROJECT_ID> \
  --config '{"notifications": {"webhookUrl": "https://example.com/webhook", "enabledEvents": ["job_failed", "job_completed"]}}' \
  --json

Step 3: Managing Project Languages

After project creation, add or remove target languages as needed.

List current project languages:

npx @globalize-now/cli-client project-languages list \
  --project-id <PROJECT_ID> \
  --json

This returns an array of project languages, each with its own project language ID (different from the global language ID). You'll need these IDs for glossary and style guide operations.

Add a language:

npx @globalize-now/cli-client project-languages add \
  --project-id <PROJECT_ID> \
  --name "Spanish" \
  --locale es \
  --json

Required: --name and --locale (BCP 47 code). Optional: --language-id to link to a specific global language.

Remove a language:

npx @globalize-now/cli-client project-languages remove \
  --project-id <PROJECT_ID> \
  --language-id <PROJECT_LANGUAGE_ID> \
  --json

Step 3.5: Patterns Management

Locale path patterns define where translation files live in the repository. Each pattern has a path template and a file format. Patterns are managed separately from repository create/update.

List patterns:

npx @globalize-now/cli-client patterns list --repository-id <REPO_ID> --json

Create a pattern:

npx @globalize-now/cli-client patterns create \
  --repository-id <REPO_ID> \
  --pattern "locales/{locale}/*.json" \
  --file-format json-nested \
  --json

Supported file formats: json-flat, json-nested, po, xliff-1, xliff-2, yaml-rails, arb, xcstrings, android-strings, chrome-messages, wxt-i18n.

Single-file formats (no {locale} segment). Most formats use one file per locale, so the pattern carries a {locale} placeholder (locales/{locale}/*.json). The xcstrings format (Apple String Catalog) is different: a single multi-locale file holds every locale, so the pattern is the catalog path itself with no {locale} segment — e.g.

npx @globalize-now/cli-client patterns create \
  --repository-id <REPO_ID> \
  --pattern "Localizable.xcstrings" \
  --file-format xcstrings \
  --json

Use "**/*.xcstrings" instead when the project has multiple catalog tables/directories.

Path-locale overrides (when the directory spelling differs from the language code). {locale} is a literal token substitution — there is no transform. A browser extension keeps its catalogs at locales/ptBR/messages.json (underscore) while the platform language is pt-BR, so the difference has to be recorded per language:

npx @globalize-now/cli-client patterns path-locale \
  --repository-id <REPO_ID> \
  --pattern-id <PATTERN_ID> \
  --language-id <PROJECT_LANGUAGE_ID> \
  --path-locale pt_BR \
  --json

--language-id is the project language UUID from project-languages list, not the global language id. Pass --clear instead of --path-locale to remove an override and fall back to the language's own code. Languages whose spelling already matches (de, fr, ja) need no entry. At repository-create time the same information goes in one shot via repositories create --path-locales '[{"pattern": …, "locale": "pt-BR", "pathLocale": "pt_BR"}]'.

Update a pattern:

npx @globalize-now/cli-client patterns update \
  --repository-id <REPO_ID> \
  --pattern-id <PATTERN_ID> \
  --pattern "locales/{locale}/{namespace}.json" \
  --json

Delete a pattern:

npx @globalize-now/cli-client patterns delete \
  --repository-id <REPO_ID> \
  --pattern-id <PATTERN_ID> \
  --json

Reorder a pattern:

npx @globalize-now/cli-client patterns reorder \
  --repository-id <REPO_ID> \
  --pattern-id <PATTERN_ID> \
  --position 0 \
  --json

Step 4: Glossary Management

Glossaries ensure specific terms are translated consistently across languages.

List glossary entries:

npx @globalize-now/cli-client glossary list \
  --project-id <PROJECT_ID> \
  --json

Create a glossary entry:

npx @globalize-now/cli-client glossary create \
  --project-id <PROJECT_ID> \
  --source-term "Dashboard" \
  --target-term "Tableau de bord" \
  --source-language-id <SOURCE_PROJECT_LANGUAGE_ID> \
  --target-language-id <TARGET_PROJECT_LANGUAGE_ID> \
  --json

--source-language-id and --target-language-id are project language UUIDs from project-languages list (Step 3), not global language IDs.

Pass --do-not-translate for terms that must stay verbatim in every language (brand names, product names, code identifiers). --target-term is still required — use the source spelling.

Delete a glossary entry:

npx @globalize-now/cli-client glossary delete \
  --project-id <PROJECT_ID> \
  --entry-id <ENTRY_ID> \
  --json

Bulk import a whole glossary in one transaction (max 10 000 entries, each with its own language pair). Existing entries for the same key are updated rather than duplicated:

npx @globalize-now/cli-client glossary bulk \
  --project-id <PROJECT_ID> \
  --entries '[{"sourceTerm":"Dashboard","targetTerm":"Tableau de bord","sourceProjectLanguageId":"<SRC_PL_ID>","targetProjectLanguageId":"<TGT_PL_ID>"},{"sourceTerm":"Globalize","targetTerm":"Globalize","sourceProjectLanguageId":"<SRC_PL_ID>","targetProjectLanguageId":"<TGT_PL_ID>","doNotTranslate":true}]' \
  --json

Preview the same import before writing anything — it reports how many entries would be created and how many updated:

npx @globalize-now/cli-client glossary preview \
  --project-id <PROJECT_ID> \
  --keys '[{"sourceTerm":"Dashboard","sourceProjectLanguageId":"<SRC_PL_ID>","targetProjectLanguageId":"<TGT_PL_ID>"}]' \
  --json

Step 5: Style Guide Management

Style guides provide translation instructions per language (e.g., "use formal register", "prefer British English spelling").

List style guides:

npx @globalize-now/cli-client style-guides list \
  --project-id <PROJECT_ID> \
  --json

Create or update a style guide:

npx @globalize-now/cli-client style-guides upsert \
  --project-id <PROJECT_ID> \
  --language-id <PROJECT_LANGUAGE_ID> \
  --instructions "Use formal register. Prefer British English spelling." \
  --json

--language-id is a project language UUID from project-languages list (Step 3).

Delete a style guide:

npx @globalize-now/cli-client style-guides delete \
  --project-id <PROJECT_ID> \
  --language-id <PROJECT_LANGUAGE_ID> \
  --json

Step 6: Organisation and Team Management

These commands are less commonly needed from an agent but are available when requested.

Organisations

npx @globalize-now/cli-client orgs list --json
npx @globalize-now/cli-client orgs delete --id <ORG_ID> --json

Note: There is no orgs create command. Creating an organisation requires an interactive (Clerk) session and is done in the web app — it is not available via API key. The CLI can list and delete orgs, and manage everything inside them.

Members

npx @globalize-now/cli-client members list --org-id <ORG_ID> --json
npx @globalize-now/cli-client members invite --org-id <ORG_ID> --email <EMAIL> --json
npx @globalize-now/cli-client members remove --org-id <ORG_ID> --membership-id <ID> --json

Members are invited by email address (--email). Optional --role flag on invite: admin or member (default: member).

API Keys

npx @globalize-now/cli-client api-keys list --org-id <ORG_ID> --json
npx @globalize-now/cli-client api-keys create --org-id <ORG_ID> --name "CI Key" --json
npx @globalize-now/cli-client api-keys revoke --org-id <ORG_ID> --key-id <KEY_ID> --json

GitLab

npx @globalize-now/cli-client gitlab install                    # OAuth flow (opens browser)
npx @globalize-now/cli-client gitlab install --no-wait --json   # Returns URL and nonce
npx @globalize-now/cli-client gitlab install-status --nonce <NONCE> --json
npx @globalize-now/cli-client gitlab connections --json
npx @globalize-now/cli-client gitlab connection-delete --id <ID> --json
npx @globalize-now/cli-client gitlab projects --connection-id <ID> --json
npx @globalize-now/cli-client gitlab branches --connection-id <ID> --project-id <PROJECT_ID> --json
npx @globalize-now/cli-client gitlab detect --connection-id <ID> --project-id <PROJECT_ID> --json

Command Reference

Additional Commands: Jobs, Namespaces, Translation Memory & Billing

These command groups manage translation work and account state beyond initial setup. They are less commonly needed during onboarding but available whenever requested.

Jobs

Translation jobs run a project's pipeline. Inspect, start, retry, and export them:

npx @globalize-now/cli-client jobs list --project-id <PROJECT_ID> --json
npx @globalize-now/cli-client jobs get --id <JOB_ID> --json
npx @globalize-now/cli-client jobs start --id <JOB_ID> --json
npx @globalize-now/cli-client jobs stats --id <JOB_ID> --json
npx @globalize-now/cli-client jobs qa-report --id <JOB_ID> --json

QA findings on a job can be dismissed and restored. --check-type identifies the QA check (e.g. placeholder, length, terminology, formatting), and --unit-id the affected translation unit:

npx @globalize-now/cli-client jobs qa-dismiss --id <JOB_ID> --unit-id <UNIT_ID> --check-type <CHECK> --json
npx @globalize-now/cli-client jobs qa-undismiss --id <JOB_ID> --unit-id <UNIT_ID> --check-type <CHECK> --json

Namespaces

Namespaces group keys within a project (e.g. per feature or page):

npx @globalize-now/cli-client namespaces list --project-id <PROJECT_ID> --json
npx @globalize-now/cli-client namespaces update --project-id <PROJECT_ID> --namespace-id <NS_ID> --name "common" --json
npx @globalize-now/cli-client namespaces delete --project-id <PROJECT_ID> --namespace-id <NS_ID> --json

There is no namespaces create command — namespaces are created automatically as keys are imported.

Translation memory

Translation memory (TM) stores prior translations for reuse. A memory is an organisation-level resource, not a project one — several projects can be attached to the same memory and then share its entries. Get a project's memory from projects get (translationMemory.id), or list every memory in the org:

npx @globalize-now/cli-client translation-memories list --json
npx @globalize-now/cli-client translation-memories get --id <TM_ID> --json   # attached projects + locales

Entries are addressed by memory ID and locale (en, fr-CA), not by project language UUID:

npx @globalize-now/cli-client translation-memories entries --id <TM_ID> --target-locale fr --json
npx @globalize-now/cli-client translation-memories count --id <TM_ID> --json
npx @globalize-now/cli-client translation-memories fresh-count --id <TM_ID> --target-locale fr --json
npx @globalize-now/cli-client translation-memories delete-entry --id <TM_ID> --entry-id <ENTRY_ID> --json

Managing the memory itself:

npx @globalize-now/cli-client translation-memories create --name "Marketing site" --json
npx @globalize-now/cli-client translation-memories rename --id <TM_ID> --name "Marketing" --json
npx @globalize-now/cli-client translation-memories clear --id <TM_ID> --target-locale fr --json   # omit the locale to clear everything
npx @globalize-now/cli-client translation-memories delete --id <TM_ID> --json

Attach a new project to an existing memory at creation time with projects create --translation-memory-id <TM_ID>; attachment is permanent.

Destructive operations hit every attached project. clear, delete-entry and delete act on the shared memory, so entries other projects contributed disappear too. Check attachedProjectCount (from translation-memories list/get) and confirm with the user before clearing or deleting. translation-memories delete only works on a memory with no attached projects.

The older project-scoped commands (translation-memory list|count|fresh-count|delete --project-id) still work — they resolve the project's memory for you — but they are deprecated, print a warning, and return entries carrying translationMemoryId instead of projectId. Prefer the translation-memories commands above.

Billing

Read the organisation's credit balance and ledger:

npx @globalize-now/cli-client billing balance --json
npx @globalize-now/cli-client billing ledger --json

billing balance resolves the organisation from your API key. Checkout and portal flows are web-only (not available via API key).

Common Gotchas

• Always use --json: The CLI auto-detects non-TTY and outputs JSON, but always pass --json explicitly when running programmatically for reliability.
• IDs are UUIDs (except --installation-id): All --id, --project-id, --org-id, etc. expect UUID values returned from prior create/list commands. Two different installation ID flags exist — they take different value types. --installation-id (used by github repos, github branches, github detect) expects the numeric GitHub installation ID (the installationId field from github installations --json, e.g. 122432012). --github-installation-id (used by repositories create/update) expects the UUID (the id field from github installations --json). Always capture both IDs from the JSON response.
• Project language IDs vs global language IDs: Glossary (--source-language-id, --target-language-id) and style guide (--language-id) commands use project language UUIDs — the ID of a language within a specific project. Get these from project-languages list, not languages list. The translation-memories commands are the exception: they take plain locales (--source-locale, --target-locale) because a memory is shared across projects.
• GitHub App required for GitHub repos: When connecting a GitHub repository, use the GitHub App flow (github installations / github install) to obtain an installation ID and pass it via --github-installation-id on repositories create. Without this, Globalize cannot access repo contents. Use github install --no-wait --json to get the install URL without blocking, present it to the user, then check completion with github install-status --nonce <NONCE> --json.
• Patterns are managed separately: After creating a repository, manage locale path patterns via patterns list/create/update/delete/reorder. The --patterns flag on repositories create is only for initial setup. Pattern changes after creation require the pattern CRUD commands.
• GitLab uses connections, not installations: For GitLab repos, use gitlab connections (not github installations) and pass --gitlab-connection-id (not --github-installation-id) on repositories create. GitLab project IDs are numeric (not UUIDs).
• Validate languages before project creation: Always fetch languages list --json and match the user's desired locales against the catalog. Use the returned UUIDs for --source-language and --target-languages — do not pass raw locale codes. Inform the user about any unsupported languages that have no catalog match.
• Auth in non-interactive contexts: The CLI does not fall back to interactive login when there's no TTY. Ensure GLOBALIZEAPIKEY is set or ~/.globalize/config.json exists.