gt 2.23.0 / @generaltranslation/api 0.5.0: Sign in and set up projects from the CLI

gt@2.23.0 brings account sign-in, project selection, scoped key creation and scriptable setup to the terminal. The accompanying @generaltranslation/api@0.5.0 and generaltranslation@9.5.2 releases add project discovery with automatic pagination.

Start with guided setup

Run gt init to configure your project. It only signs in when it creates a project or key:

npx gt init

Use gt login to sign in without running setup, or npx gt login --no-browser to approve on another device. Both require human approval.

gt whoami checks your signed-in identity, and gt logout removes the saved login. Use scoped API keys from your CI provider's secret store for unattended workflows.

Run setup from scripts and agents

Every setup question has a flag. Without a terminal, or with --no-interactive, gt init lists any missing options before changing files, and --json reports sign-in, handoff and result events:

npx gt init --no-interactive --json --defaults --locales fr es --no-dev-credentials

--defaults accepts the recommended local choices but never creates projects or keys.

Choose a project and key permissions

gt init can select an accessible project or create one in an Organisation where you have permission, then save its ID and a development runtime key in .env.local.

The key grants only project:translations:generate: it is for local runtime translations, not CLI uploads or CI. Existing GT_API_KEY values remain unchanged. Next.js App Router projects get NEXT_PUBLIC_GT_PROJECT_ID and NEXT_PUBLIC_GT_DEV_API_KEY, so client components also translate in development; keep both out of production builds (see Next.js credentials).

Use gt api-key create when you want to create an additional project key with permissions of your choosing:

npx gt api-key create --project-id your-project-id \
  --name "Runtime translations" \
  --permission project:translations:generate

You must be allowed to create keys and grant each selected permission. The command prints the secret only once, so store it securely. For CI, choose permissions that cover the whole workflow rather than reusing this generate-only example. Never include API keys in deployed browser or mobile bundles.

Use typed API calls and check job results

Use paginate from generaltranslation/api to iterate over every project accessible to your API key without having to handle cursors:

import { listProjects, paginate } from 'generaltranslation/api';

for await (const project of paginate(listProjects, { client })) {
  console.log(project.id, project.name);
}

With a createApiClient client, HTTP failures in throwOnError calls now throw an ApiError with the HTTP status in code.

The API client's polling helpers let you wait for translation jobs and return complete: false on timeout. Completion does not mean that every job succeeded. Check job results before downloading translations.

Diagnostic formatting is now available from the public generaltranslation/diagnostics entry point. Tools can format actionable messages without importing the full Core entry point.

Upgrading

• Upgrade to list projects and Organisations. The API now returns them in items instead of projects or orgs and rejects cursors issued before this change. Earlier CLI versions cannot list them in gt init. Direct HTTP and SDK callers should read items and restart pagination.
• Catch ApiError from throwing calls. HTTP failures in throwOnError calls and awaitJobs throw ApiError instead of the decoded response body. Calls without throwOnError still return the body in error.
• Move src/gt.config.json. The CLI no longer reads it. Move it to the project root, or pass --config src/gt.config.json.
• Replace gt auth and --key-type. Use login for account authentication, init for guided project setup, and explicit key creation for additional credentials. gt configure is not a side-effect-free substitute: depending on your setup, it can install dependencies and provision credentials.
• Keep runtime and tooling credentials separate. GT_DEV_API_KEY remains a framework runtime setting. Signing in alone does not configure runtime SDK credentials. Explicit API keys still take precedence over the CLI's saved login; see credential selection.
• Check retry assumptions. Management POST requests do not automatically retry on network or server failures, but 429 responses may still be retried when retries are enabled. Core runtime translation does not automatically retry on these failures or on 429 responses. Avoid blindly repeating project or key creation: each successful request creates another resource.
• Retain supported compatibility APIs. Core's devApiKey fallback and getProjectData remain available but are deprecated. Use apiKey, and prefer getProjectInfo for new project-info calls.
• Handle validation and result changes. Unsupported model-provider values now fail before a request is sent. Font upload results no longer include the deduped field.