1. Help Center
  2. Phrase for Developers
  3. Using Phrase from the command line

Usage

The Phrase Client lets you access all API endpoints and easily syncs your locale files between your source code and Phrase.

We have recently updated our CLI, instead of phraseapp, it is now called phrase.
Although we try to keep things as similar and compatible as possible, there might be some changes.
All documentation now refers to the phrase CLI.
If you have any questions, please contact us at support@phrase.com.

Working with the Phrase Client

The Phrase Client lets you access all API endpoints and easily syncs your locale files between your source code and Phrase.

Accessing API endpoints

The Phrase Client can be used to access all API endpoints. For example, to list all your projects just type:

$ phrase projects list --access_token YOUR_ACCESS_TOKEN

To see a list of all available commands, simply execute:

$ phrase

Use the --help flag to see the supported options for a command:

$ phrase locales list --help

Besides these low level functions there are two helpful abstractions described in the Push & Pull section.


 Authentication using Phrase credentials


You can specify your username with the --username flag, in which case you will be asked for you password:

$ phrase projects list --username user@example.com
Password: ********

If two-factor authentication is activated for your account, a valid multi factor token must be provided via the --tfa flag:

$ phrase projects list --username user@example.com --tfa
Password: ********
TFA: ********

Authentication using Access Token


Use the --access_token flag to specify your access token:

$ phrase projects list --access_token YOUR_ACCESS_TOKEN

or use the PHRASE_ACCESS_TOKEN environment variable to store your token:

export PHRASE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

Note: Setting environment variables will work differently on different platforms.

For your convenience, you might want to store the access token in your .phrase.yml configuration file.


If two-factor authentication is activated for your account, a valid multi factor token must be provided via the --x_phrase_app_otp flag:

$ phrase projects list --access_token YOUR_ACCESS_TOKEN --x_phrase_app_otp PASSWORD

You can also provide the token in interactive mode with the --tfa flag:

$ phrase projects list --access_token YOUR_ACCESS_TOKEN --tfa
TFA: ********

The access token will be read from your .phrase.yml configuration file by default, but you can override this behaviour by using the flags or env variable mentioned above. In this case, the token provided via the flag or environment variable will be used, instead of the one stored in your .phrase.yml configuration file. Also, tokens provided via flags will override tokens provided via the environment variable.

Push & Pull

Use the push and pull commands to upload and download locale files. Instead of command line arguments, push and pull rely on the configuration stored in a .phrase.yml configuration file that lives in your project root folder.

See the following example configuration for uploading and downloading locale files of a typical Rails application:

phrase:
  access_token: "YOUR_ACCESS_TOKEN"
  project_id: "YOUR_PROJECT_ID"
  file_format: "yml"
  push:
    sources:
      - file: "./config/locales/<locale_name>.yml"
  pull:
    targets:
      - file: "./config/locales/<locale_name>.yml"

Use the push command to upload your locale files to the project identified by project_id matching the files de.yml and en.yml in the config/locales folder:

$ phrase push
Uploading config/locales/de.yml
Uploaded config/locales/de.yml successfully.
Uploading config/locales/en.yml
Uploaded config/locales/en.yml successfully.

Use the pull command to download locale files from the project identified by project_id to their respective file paths:

$ phrase pull
Downloaded de to config/locales/de.yml
Downloaded en to config/locales/en.yml

See the configuration guide to learn more about all supported options.

Rate limit support
The client supports the rate limit for locale downloads. When the rate limit is reached, the client will wait until the rate limit has expired and will continue downloading locales afterwards. The client shows: "rate limit exceeded, download will resume in x seconds".

Upload cleanup

The upload cleanup command is provided to delete unmentioned keys of an upload. After pushing you locale files to Phrase you maybe want to delete all keys that are not contained in your default locale or some other locale. To get this task done the cli client provides the upload cleanup command. As argument you have to set the <UploadID>. You can get the <UploadID> by using the uploads list command.

$ phrase uploads cleanup --id <YOUR_UPLOAD_ID>

Format options

Several formats like CSV support additional format options during upload. You can access them by prefixing your options with --format_options.

phrase uploads create\
--project_id <ProjectID> \
--file=en.csv --file_format=csv \
--locale_mapping ‘{"en":3, "de":2}’ \
--format_options ‘{“key_index”:1}’ \
--access_token YOUR_ACCESS_TOKEN

Proxy

If you’re behind a proxy, you can specify your proxy settings using the HTTPS_PROXY environment variable:

export HTTPS_PROXY=https://user:password@host:port