# gt: General Translation CLI tool: gt init URL: https://generaltranslation.com/en-GB/docs/cli/reference/commands/init.mdx Docs index: https://generaltranslation.com/llms.txt Description: Run the General Translation setup wizard to configure a project. API reference for the gt init command. `init` is the default command: running `npx gt` with no command runs it. The setup wizard detects your framework and, depending on the project, installs dependencies, configures your framework, creates a `gt.config.json`, and generates credentials. For a step-by-step walkthrough, see [Configuring the CLI](/docs/cli/guides/configuring). ```bash npx gt init ``` ## How it works [#how-it-works] 1. Detects your framework. For a Next.js App Router or Mintlify project, it offers to connect the [Locadex](/docs/platform/locadex/quickstart) AI agent instead. 2. For a React-based project, it can optionally install the matching runtime and configure the framework (experimental). Next.js App Router apps get [`GTProvider`](/docs/react/reference/components/gt-provider) and `withGTConfig`. Vite apps get an [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) bootstrap that runs before the existing app entry. TanStack Start apps get `gt-tanstack-start`, `src/loadTranslations.ts`, [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) in `src/start.ts`, [`initializeGT`](/docs/react/tanstack-start/setup#initialize) in `src/router.tsx`, and [`GTProvider`](/docs/react/reference/components/gt-provider) in the root route. Other React apps only get the library installed. 3. Resolves the default and target locales, and creates or updates `gt.config.json`. `--locales` replaces the configured locale list and `--file-formats` replaces the formats that setup offers; other formats and unrelated settings are kept. An invalid `gt.config.json` stops setup before any changes are made. For local Vite or TanStack Start storage, it also creates a [`loadTranslations`](/docs/react/reference/functions/load-translations) file and empty target-locale files. 4. Installs `gt` as a dev dependency when the configured workflow requires a persistent CLI installation. Vite framework setup does not add `gt`; continue to run it with `npx gt`. 5. Optionally selects or creates a project and provisions a development runtime key in `.env.local`. Setup signs in only for this step, before changing any files, and uses an explicit tooling key or saved login when available. Local Vite and TanStack Start setups ask whether to enable live development translations (default: no); declining skips sign-in, project discovery and key creation. *Note: The React setup step is experimental and may not work for every project. Review the changes it makes.* ### Project selection and runtime credentials A configured project ID is reused. Otherwise, the wizard lists [accessible projects](/docs/platform/openapi/reference/project/list-projects) for you to select from, or offers to create one. When creating a project, choose an Organisation in which you have permission to create projects. If none are available, create an Organisation in the Dashboard or ask an administrator for access. Interactive project names default to the app directory name; headless creation requires `--project-name`. Creation uses your selected source locale. Selecting an existing project does not require Organisation project-creation access. Provisioning a key still requires key-write authorisation and permission to delegate runtime generation. An invalid or insufficient explicit tooling key never falls back to login. Provisioning creates one key named `Development key (gt init)` with only `project:translations:generate`. It writes the project ID and development key without printing the secret or changing an existing `GT_API_KEY`. This runtime key does not authenticate subsequent CLI management commands; use your login or a separately scoped tooling key (see [credentials](/docs/cli/guides/configuring#credentials)). Existing framework runtime credentials for the same project allow provisioning to be skipped. Server-only setups with a project ID and `GT_API_KEY` also skip it; frameworks that translate in the browser do not treat an unprefixed `GT_API_KEY` as a runtime key. The generated variables are `GT_PROJECT_ID` and `GT_DEV_API_KEY`, with the following prefixes for frameworks that translate in the browser: * Next.js (App Router and Pages Router): `NEXT_PUBLIC_` * Vite and TanStack Start: `VITE_` * Gatsby: `GATSBY_` * React: `REACT_APP_` * Redwood: `REDWOOD_ENV_` Other setups use unprefixed variables. Development keys are for local development only; for production credentials, see [Next.js credentials](/docs/react/nextjs/config#credentials). Never include API keys in deployed browser or mobile bundles. ## Flags [#flags] Flags answer the wizard's questions, so a run asks only what is left. The same configuration and credential flags work with [`gt configure`](/docs/cli/reference/commands/configure). ### Setup mode | Parameter | Description | Type | Optional | Default | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------- | -------- | ---------------- | | `--no-interactive` | Never prompt. Stops before changing files and lists any options still needed. Automatic when stdin or stdout is not a terminal. | `boolean` | Yes | `false` | | `--json` | Write sign-in, handoff and result events to stdout as JSON lines, and all other output to stderr. Implies `--no-interactive`. | `boolean` | Yes | `false` | | `--defaults` | Accept the recommended value for every local choice that no flag or `gt.config.json` answers. Never creates projects or keys. | `boolean` | Yes | — | | `--no-defaults` | Do not offer the recommended defaults. | `boolean` | Yes | — | | `-c, --config ` | Path to the config file. | `string` | Yes | `gt.config.json` | ### Configuration | Parameter | Description | Type | Optional | Default | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------- | ---------------------------------------------------- | | `--src ` | Glob patterns for the app's source code. | `string[]` | Yes | [Framework-specific](/docs/cli/reference/config#src) | | `--default-locale ` | Default locale, such as `en`. | `string` | Yes | `en` with `--defaults` | | `--locales ` | Target locales, such as `fr es`. Replaces the configured list. | `string[]` | Yes | — | | `--storage ` | Where framework translations are stored: `local` or `cdn`. `gt-vue` supports only `local`. | `string` | Yes | `local` with `--defaults` | | `--translations-dir ` | Directory for local translation files. | `string` | Yes | Framework-specific with `--defaults` | | `--file-formats ` | `json`, `md`, `mdx`, `ts`, `js`, `yaml`, or `none`. Replaces the configured selection among these; other configured formats are kept, with a warning. | `string[]` | Yes | `none` with `--defaults` in framework projects | | `--file-patterns ` | `=` patterns that include `[locale]`, such as `json=./locales/[locale]/*.json`. Selects the format. | `string[]` | Yes | `./**/[locale]/*.` with `--defaults` | | `--package-manager ` | Package manager for installs: `npm`, `yarn_v1`, `yarn_v2`, `pnpm`, `bun` or `deno`. Detection uses the nearest `packageManager` or `devEngines` field, lockfile or recognised workspace indicator, searching up to the Git root. | `string` | Yes | Detected | ### Project and development credentials | Parameter | Description | Type | Optional | Default | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------- | --------------------------------- | | `--dev-credentials` | Save a project ID and a new development key to `.env.local`. Use `--no-dev-credentials` to skip. | `boolean` | Yes | — | | `--live-translations` | Local Vite or TanStack Start storage: set up live development translations, which creates a development key. Use `--no-live-translations` to skip. | `boolean` | Yes | `false` with `--defaults` | | `--project-id ` | Existing project for the development credentials. | `string` | Yes | — | | `--create-project` | Create a new project for the development credentials. | `boolean` | Yes | `false` | | `--org-id ` | Organisation that owns the new project. Only needed if you have access to more than one. | `string` | Yes | — | | `--project-name ` | Name of the new project. | `string` | Yes | App directory name, when prompted | ### Framework setup These flags apply to `gt init` only. In `gt-vue` projects, `gt init` accepts the [`gt configure`](/docs/cli/reference/commands/configure) flags and skips React setup. | Parameter | Description | Type | Optional | Default | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------- | --------------------------- | | `--locadex` | Mintlify and Next.js App Router: hand setup over to the Locadex AI agent through GitHub. Use `--no-locadex` to set up locally. | `boolean` | Yes | `false` with `--defaults` | | `--react-setup` | React projects: install the library and, for Next.js App Router, Vite or TanStack Start, add its setup (see [How it works](#how-it-works)). Use `--no-react-setup` to leave application source unchanged. | `boolean` | Yes | `true` with `--defaults` | | `--framework ` | React framework for `--react-setup`. Overrides detection. | `string` | Yes | Detected, with `--defaults` | | `--format` | Next.js App Router: format files changed by setup with the detected formatter. Use `--no-format` to skip. | `boolean` | Yes | `true` with `--defaults` | ## Headless runs [#headless] A non-interactive run resolves each answer from its flag, then `gt.config.json`, then the recommended value when `--defaults` is set. If an answer is still missing, it exits before changing any files and lists the options to pass. Development credentials are never created by default. For local Vite and TanStack Start storage, pass `--live-translations` with a project ID or `--create-project --project-name `, or pass `--no-live-translations`. For other setups, use `--dev-credentials` or `--no-dev-credentials`. Do not combine the `--[no-]live-translations` and `--[no-]dev-credentials` flag families; the CLI rejects any such pair before changing any files. If runtime credentials already exist for the project, this step is skipped. Setup signs in only when it provisions credentials and has no tooling key or saved login. Without a terminal, sign-in uses a device code and waits for someone to approve it; it does not open a browser. With `--json`, the command writes one JSON object per line, identified by its `type` field: * `authorization_required` — `verificationUri`, `userCode` and, when available, `verificationUriComplete`. * `handoff` — the Locadex GitHub `url`, with `reason: "locadex"`. * `result` — `command`, `outcome` (`success`, `needs_human_action` or `failed`), `completedSteps` and, when present, `url`, `actions` for manual follow-up, `missingOptions` and `error`. `completedSteps` leaves `gt.config.json` and generated translation-loader files out of the list when they are unchanged. When either file changes, the step identifies it as created or updated. ## Example [#example] ```bash # Run the full setup wizard npx gt init # Running gt with no command does the same thing npx gt # Headless local setup: no new project or development key npx gt init --no-interactive --defaults --locales fr es --no-dev-credentials --json ``` ## Other notes [#notes] * `init` shares its configuration, loader, CLI installation and credential flow with [`gt configure`](/docs/cli/reference/commands/configure), and adds the experimental React setup step. It does not run [`gt setup`](/docs/cli/reference/commands/setup), which uploads your source files. * In a monorepo, run `init` from the specific app directory. The command stops without changing files at a workspace root with `pnpm-workspace.yaml` or a `workspaces` field, unless it lists only the app itself. * Automatic setup is not available for Electron applications. * The API key and project ID are not required to use `gt-react` or `gt-next` — they are only needed to call the General Translation API. * If the experimental React setup does not work for your project, set it up manually using the [React](/docs/react/react-quickstart) docs. * Git must be installed when provisioning development credentials. Keep `.env.local` untracked and Git-ignored, and use your repository's normal Git configuration. Init refuses unsafe file locations or Git overrides. A symlink must point to an existing regular file that meets the same safety requirements. Existing unrelated environment variables are preserved. * Run only one setup command at a time. If `.env.local` cannot be updated, including because of unsupported multiline assignments, any newly created projects or keys may remain. Earlier configuration and dependency changes are not reverted. ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.