Globalize now cli use

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).

2. 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.

3. 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 <GITHUB_INSTALLATION_ID> (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 <GITHUB_INSTALLATION_ID> (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 <new_keys_only|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 <new_keys_only|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

Section	Fields	Description
qa	enabledChecks ("placeholder", "length", "terminology", "formatting"), lengthRatioBounds (object keyed by locale, each {min, max}), aiReviewScope ("enabled", "disabled")	Quality assurance checks and thresholds
defaultProvider	string	Default translation provider
providerOverrides	object keyed by locale → provider string	Per-language provider overrides
deeplFormality	object keyed by locale → formality string	DeepL formality settings per language
github	prTranslations (boolean), ignoreDraftPrs (boolean)	GitHub integration behaviour
gitlab	mrTranslations (boolean), ignoreDraftMrs (boolean)	GitLab integration behaviour
notifications	webhookUrl (string), webhookSecret (string), emailRecipients (string[]), enabledEvents ("job_failed", "qa_issues", "delivery_failed", "job_completed")	Webhook and email notification settings

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.

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.

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.

Delete a glossary entry:

npx @globalize-now/cli-client glossary delete \
  --project-id <PROJECT_ID> \
  --entry-id <ENTRY_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

Command	Required flags	Optional flags
auth login	(interactive)	--no-wait
auth complete	--device-code, --code-verifier	--interval, --expires-in
auth status
auth logout
orgs list
orgs delete	--id
projects list
projects create	--name, --source-language (ID), --target-languages (IDs)
projects update	--id	--name, --source-language, --target-languages, --config (JSON)
projects get	--id
projects delete	--id
projects refs	--id
projects scorecards		--limit
projects budget	--id
projects rotate-webhook-secret	--id
languages list
languages get	--id
project-languages list	--project-id
project-languages add	--project-id, --name, --locale	--language-id
project-languages remove	--project-id, --language-id
repositories list	--project-id
repositories create	--project-id, --git-url, --provider	--branches, --github-installation-id, --gitlab-connection-id, --patterns, --import-mode, --import-scope
repositories update	--id	--git-url, --branches, --github-installation-id, --gitlab-connection-id, --provider, --detected-framework, --import-mode, --import-scope
repositories delete	--id
repositories detect	--id
repositories branches	--id
repositories discover	--id
repositories translate	--id	--branch, --delivery-mode (push|pr)
patterns list	--repository-id
patterns create	--repository-id, --pattern, --file-format	--position
patterns update	--repository-id, --pattern-id	--pattern, --file-format
patterns delete	--repository-id, --pattern-id
patterns reorder	--repository-id, --pattern-id, --position
patterns bulk	--repository-id, --patterns (JSON)
github install		--no-wait
github install-status	--nonce
github installations
github repos	--installation-id
github branches	--installation-id, --owner, --repo
github detect	--installation-id, --owner, --repo
gitlab install		--no-wait
gitlab install-status	--nonce
gitlab connections
gitlab connection-delete	--id
gitlab projects	--connection-id
gitlab branches	--connection-id, --project-id
gitlab detect	--connection-id, --project-id
glossary list	--project-id
glossary create	--project-id, --source-term, --target-term, --source-language-id, --target-language-id
glossary delete	--project-id, --entry-id
style-guides list	--project-id
style-guides upsert	--project-id, --language-id, --instructions
style-guides delete	--project-id, --language-id
style-guides generate	--project-id, --language-id
style-guides apply	--project-id, --language-id, --generation-id, --instructions	--context, --invalidate-tm
style-guides quota	--project-id
api-keys list	--org-id
api-keys create	--org-id, --name
api-keys revoke	--org-id, --key-id
members list	--org-id
members invite	--org-id, --email	--role
members remove	--org-id, --membership-id
namespaces list	--project-id
namespaces update	--project-id, --namespace-id, --name
namespaces delete	--project-id, --namespace-id
translation-memory list	--project-id	--query, --source-language-id, --target-language-id, --limit, --cursor
translation-memory delete	--project-id, --entry-id
translation-memory count	--project-id	--target-language-id
translation-memory fresh-count	--project-id, --target-language-id
jobs list		--project-id, --status, --limit, --offset
jobs get	--id
jobs start	--id
jobs retry	--id
jobs stats	--id
jobs qa-report	--id
jobs qa-dismiss	--id, --unit-id, --check-type	--reason, --note
jobs qa-undismiss	--id, --unit-id, --check-type
jobs export	--id	--target-lang
jobs export-manifest	--id
jobs units	--job-id, --target-project-language-id	--filter, --search, --limit, --cursor
jobs unit-get	--job-id, --unit-id
jobs files	--id	--limit, --cursor
jobs redeliver	--id
billing balance
billing ledger		--type, --grouped, --limit, --cursor

---

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. --source-language-id / --target-language-id are project language UUIDs (from project-languages list):

npx @globalize-now/cli-client translation-memory list --project-id <PROJECT_ID> --target-language-id <PROJECT_LANGUAGE_ID> --json
npx @globalize-now/cli-client translation-memory count --project-id <PROJECT_ID> --json
npx @globalize-now/cli-client translation-memory fresh-count --project-id <PROJECT_ID> --target-language-id <PROJECT_LANGUAGE_ID> --json
npx @globalize-now/cli-client translation-memory delete --project-id <PROJECT_ID> --entry-id <ENTRY_ID> --json

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.
• 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 GLOBALIZE_API_KEY is set or ~/.globalize/config.json exists.