# General Translation Changelog: gt 2.23.0 / @generaltranslation/api 0.5.0: Sign in and set up projects from the CLI
URL: https://generaltranslation.com/en-GB/blog/gt_v2_23_0_generaltranslation-api_v0_5_0.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Sign in, set up a project and create keys with explicit permissions from the CLI, or run setup headlessly from scripts and agents.
Authors: Chenxin (Cyan) Yan
Published: 2026-09-29

`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`](/docs/cli/reference/commands/init) to configure your project. It only signs in when it creates a project or key:

```bash
npx gt init
```

Use [`gt login`](/docs/cli/reference/commands/login) to sign in without running setup, or [`npx gt login --no-browser`](/docs/cli/reference/commands/login#flags) to approve on another device. Both require human approval.

[`gt whoami`](/docs/cli/reference/commands/whoami) checks your signed-in identity, and [`gt logout`](/docs/cli/reference/commands/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`](/docs/cli/reference/commands/init#headless) lists any missing options before changing files, and `--json` reports sign-in, handoff and result events:

```bash
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`](/docs/cli/reference/commands/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](/docs/react/nextjs/config#credentials)).

Use [`gt api-key create`](/docs/cli/reference/commands/api-key-create) when you want to create an additional project key with permissions of your choosing:

```bash
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`](/docs/platform/core/reference/api-client#pagination) from [`generaltranslation/api`](/docs/platform/core/reference/api-client) to iterate over every project accessible to your API key without having to handle cursors:

```ts
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`](/docs/platform/core/reference/api-client#api-error) with the HTTP status in `code`.

The [API client's polling helpers](/docs/platform/core/reference/api-client#job-polling) 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`](/docs/platform/core/reference/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`](/docs/cli/reference/commands/init). Direct HTTP and SDK callers should read `items` and restart pagination.
* **Catch `ApiError` from throwing calls.** HTTP failures in `throwOnError` calls and [`awaitJobs`](/docs/platform/core/reference/api-client#job-polling) 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`](/docs/cli/reference/commands/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](/docs/cli/guides/configuring#credentials).
* **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`](/docs/platform/core/reference/gt-class-methods/translation/get-project-data) remain available but are deprecated. Use `apiKey`, and prefer [`getProjectInfo`](/docs/platform/core/reference/gt-class-methods/project/project-management#get-project-info) 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.

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.