# gtx-cli: General Translation CLI tool: Usage Guide
URL: https://generaltranslation.com/en-US/docs/cli/reference/usage.mdx
---
title: Usage Guide
description: Usage guide for the GT command line tool
---
## Overview
This guide will walk you through the process of using General Translation's CLI tool (`gtx-cli`) to translate your project.
The CLI tool is compatible with any i18n library, whether you are using `gt-next`, `gt-react`, or third-party libraries like `next-intl` or `i18next`.
The CLI tool is responsible for connecting your project to General Translation's AI translation service.
There are several ways to use the CLI tool, please navigate to the relevant section for your use case.
## Installation
To install the CLI tool, run the following command:
```bash
npm i gtx-cli
```
```bash
yarn add --dev gtx-cli
```
```bash
bun add --dev gtx-cli
```
```bash
pnpm add --save-dev gtx-cli
```
---
## Use cases
### Translating GT projects
The CLI tool can be used to translate your projects which use `gt-next` or `gt-react`.
This guide assumes you have already set up your codebase to use `gt-next` or `gt-react` according to the [gt-next](/docs/next/tutorials/quickstart) or [gt-react](/docs/react/tutorials/quickstart) tutorials.
If you followed the quickstart guides for `gt-next` or `gt-react`, your
project has only been internationalized in your development environment.
When shipping your project to production, you will need to actually generate
and save the translations. This step is necessary to ensure that your API
keys are not exposed to the public, due to client-side vulnerabilities for
frameworks like React.
1. First, you will need to configure your project's GT settings.
```bash
npx gtx-cli configure
```
This command will automatically generate an API key and project ID for your project via the dashboard.
However, if you would like to manually set the API key and project ID, follow steps 2 and 3 below.
2. Next, you will need to create a project in the [General Translation dashboard](https://generaltranslation.com/dashboard).
After creating a project, you will need to generate a production API key. Navigate to the "API Keys" page and click the "Create API Key" button.
3. Then, add your API key and Project ID to your environment variables.
```bash title=".env"
GT_API_KEY=
GT_PROJECT_ID=
```
4. Finally, run the translation command.
```bash
npx gtx-cli translate
```
By default, the CLI tool will publish the translations to the General
Translation CDN, so they are ready to be used in your project. If you would
like to disable this behavior (for example, if you are loading translations
from a different source), disable the `CDN` setting in the [dashboard project
settings](https://dash.generaltranslation.com/en/settings/project).
See the [API reference](/docs/cli/translate) for more information on the `translate` command.
### Translating language files (3rd party i18n libraries or standalone GT projects)
The CLI tool allows you to translate language files for 3rd party i18n libraries or with a stand-alone implementation of [`gt-next`](/docs/next/concepts/stand-alone) or [`gt-react`](/docs/react/concepts/stand-alone).
Most i18n libraries rely on JSON files to store translation data.
The CLI tool can be used to automatically translate these JSON files into your desired languages.
1. First, you will need to configure your project's GT settings.
```bash
npx gtx-cli configure
```
This command will create a `gt.config.json` file in the root of your project, containing some basic configuration settings, such as your project's default locale and supported locales.
This command will automatically generate an API key and project ID for your project via the dashboard.
However, if you would like to manually set the API key and project ID, follow steps 2 and 3 below.
2. Next, you will need to create a project in the [General Translation dashboard](https://generaltranslation.com/dashboard).
After creating a project, you will need to generate a production API key. Navigate to the "API Keys" page and click the "Create API Key" button.
3. Then, add your API key and Project ID to your environment variables.
```bash title=".env"
GT_API_KEY=
GT_PROJECT_ID=
```
4. Finally, run the translation command.
```bash
npx gtx-cli translate
```
By default, the CLI tool will look for files to translate according to the `files` property in your `gt.config.json` file.
It will use the `defaultLocale` specified in your `gt.config.json` file as the source language.
Translated files will be saved to the corresponding output location specified in your `gt.config.json` file.
See the [configuration](/docs/cli/reference/config) docs for more information on the `files` property.
If your files are not being translated, it is likely that your `gt.config.json` file is not configured correctly.
The `files` property should include glob patterns that match your language files, using the `[locale]` placeholder.
For example, if your language files are stored in the `src/locales` directory, your `gt.config.json` file should look like this:
```json
{
"defaultLocale": "en",
"locales": ["fr", "es"],
"files": {
"json": {
"include": ["src/locales/[locale]/*.json"]
}
}
}
```
### Generating language files for GT projects
The CLI tool can be used to generate language files for projects which use `gt-next` or `gt-react`.
This use case is useful if you would like to use your own translation provider.
Unlike other i18n libraries, `gt-next` and `gt-react` support in-line translations, meaning there is no traditional JSON file structure containing keys and values for each language.
This means that in order to track changes to text, GT libraries store the hashes of the original text in the source code.
This internal data structure (containing hashes) is hard to work with, and therefore the CLI tool provides a handy command to generate language files for your project.
1. First, you will need to configure your project's GT settings.
```bash
npx gtx-cli configure
```
When asked if you want to save translations on the GT CDN, select the "No" option.
2. Run:
```bash
npx gtx-cli generate
```
This command will generate a source file for your default locale, and all other locales you have configured for your project.
The content for each file is the same, and will be merged with any previous translations you have in your project.
See the [API reference](/docs/cli/generate) for more information on the `generate` command.
---
## Notes
- [`gtx-cli translate`](/docs/cli/translate) is used to automatically generate translations for your project.
- If you are using a 3rd party i18n library, you can automatically update all of your translation JSON files every time your project changes. Just add the [`gtx-cli translate`](/docs/cli/translate) command to your build or CD process before the build command to automatically add translations to your project.
## Next steps
- See the [CLI API reference](/docs/cli) for more information.