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

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:

$ phraseapp projects list --access-token YOUR_ACCESS_TOKEN

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

$ phraseapp

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

$ phraseapp locales list --help

Besides these low level functions there are two helpful abstractions described in the second next section.


There are two methods available for authentication:

  1. Using your Phrase credentials (username and password)
  2. Using an Access Token

Authentication using Phrase credentials

Specify your username with the --username flag:

$ phraseapp projects list --username
Password: ********

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

$ phraseapp projects list --username --tfa
Password: ********
TFA: ********

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

Authentication using Access Token

Use the --access-token flag to specify the Access Token:

$ phraseapp projects list --access-token YOUR_ACCESS_TOKEN

or use the PHRASEAPP_ACCESS_TOKEN environment variable:


Note: How to set an environment variable works different for each platform.


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 .phraseapp.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:

  access_token: "YOUR_ACCESS_TOKEN"
  project_id: "YOUR_PROJECT_ID"
  file_format: "yml"
      - file: "./config/locales/<locale_name>.yml"
      - 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:

$ phraseapp 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:

$ phraseapp 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.

$ phraseapp upload cleanup <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.

phraseapp upload create <ProjectID> \
--file=en.csv --file-format=csv \
--locale-mapping.en 2 \
--format-options.key_index 1 \
--access-token YOUR_ACCESS_TOKEN


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

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

Skip SSL verification

To disable SSL certificate validation you can use the PHRASEAPP_INSECURE_SKIP_VERIFY environment variable: