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


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 second next section.


Authentication using Access Token

Use the --access_token flag to specify the Access Token:

$ phrase projects list --access_token YOUR_ACCESS_TOKEN

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

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:

  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:

$ 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 upload 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


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