> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prismy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Prismy Hosted — push & pull

> Sync translation files with Prismy Hosted using the CLI

Use **`prismy push`** and **`prismy pull`** when you use **Prismy Hosted** without native GitHub/GitLab. You upload source files to Prismy and download translated files (locally or in CI).

<Note>
  Using **GitHub or GitLab** with Prismy? Use [prismy generate](/tech/cli/github-gitlab) instead.
</Note>

## Authentication

The CLI looks for an API token in this order:

1. `--api-token` (flag)
2. `PRISMY_API_TOKEN` environment variable
3. Stored key from `prismy auth` (only when **not** in CI)

In CI, you must set `--api-token` or `PRISMY_API_TOKEN`; the CLI will not prompt.

Get your token from [Prismy Settings](https://app.prismy.io/settings).

***

## prismy push

Upload a local translation file to Prismy.

```bash theme={null}
prismy push <filePath> --repo-id <repoId> --language <lang> --bundle-name <bundle>
```

**Required:** `--repo-id`, `--language`, `--bundle-name`

Example:

```bash theme={null}
prismy push ./locales/en/common.json \
  --repo-id 25060c5dfa \
  --language en-US \
  --bundle-name common
```

### Push options

| Option                    | Description                                                   |
| ------------------------- | ------------------------------------------------------------- |
| `--override`              | Replace the file entirely; otherwise only new keys are merged |
| `--no-auto-translate`     | Do not auto-translate new keys to other languages             |
| `--wait-for-translations` | Wait for translations to finish before exiting (useful in CI) |
| `--branch`                | Target branch (Prismy may create it from main)                |
| `--user`                  | Author username/email for the change                          |
| `--tags`                  | Static tags for new/edited keys                               |

### File formats

* **JSON, .arb, .xcstrings**: Parsed and sent as structured JSON.
* **Other (.yaml, .po, .resx, .xml, .ts, .js)**: Sent as raw content with format metadata.

***

## prismy pull

Download a translation file from Prismy. The CLI writes JSON to the path you give.

```bash theme={null}
prismy pull <filePath> --repo-id <repoId> --language <lang> --bundle-name <bundle>
```

Example:

```bash theme={null}
prismy pull ./locales/en/common.json \
  --repo-id 25060c5dfa \
  --language en-US \
  --bundle-name common
```

**Options:** `--repo-id`, `--language`, `--bundle-name` (required); `--branch` (default: main); `--api-token`.

The file is created or overwritten. If the file does not exist on Prismy, you get an empty object `{}`. For non-JSON formats (e.g. YAML, PO), use the CDN URL from your Prismy Hosted configuration.

***

## CI setup

Use a pipeline to push the source file, wait for translations, then pull translated files.

### Secret / variable

| Name               | Description           | Secret |
| ------------------ | --------------------- | ------ |
| `PRISMY_API_TOKEN` | API token from Prismy | Yes    |

Optional: `PRISMY_REPO_ID`, `PRISMY_BUNDLE_NAME` (or pass `--repo-id` / `--bundle-name` in the script).

### GitHub Actions

**.github/workflows/prismy-sync.yml**

```yaml theme={null}
name: Prismy sync

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  prismy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install Prismy CLI
        run: npm install -g prismy-cli

      - name: Push source and wait for translations
        env:
          PRISMY_API_TOKEN: ${{ secrets.PRISMY_API_TOKEN }}
        run: |
          prismy push src/i18n/en.json \
            --repo-id "${{ vars.PRISMY_REPO_ID }}" \
            --language en-US \
            --bundle-name "${{ vars.PRISMY_BUNDLE_NAME }}" \
            --wait-for-translations

      - name: Pull translated files
        env:
          PRISMY_API_TOKEN: ${{ secrets.PRISMY_API_TOKEN }}
        run: |
          prismy pull src/i18n/en.json --repo-id "${{ vars.PRISMY_REPO_ID }}" --language en-US --bundle-name "${{ vars.PRISMY_BUNDLE_NAME }}"
          prismy pull src/i18n/es.json --repo-id "${{ vars.PRISMY_REPO_ID }}" --language es-ES --bundle-name "${{ vars.PRISMY_BUNDLE_NAME }}"
          prismy pull src/i18n/fr.json --repo-id "${{ vars.PRISMY_REPO_ID }}" --language fr-FR --bundle-name "${{ vars.PRISMY_BUNDLE_NAME }}"

      - name: Commit and push changes
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add src/i18n/
          git diff --staged --quiet || git commit -m "chore(i18n): sync translations from Prismy"
          git push
```

Add `PRISMY_API_TOKEN` in **Settings → Secrets and variables → Actions**. Optionally add variables `PRISMY_REPO_ID` and `PRISMY_BUNDLE_NAME`, or hardcode them in the YAML.

### GitLab CI

Add a job (or merge into `.gitlab-ci.yml`):

```yaml theme={null}
prismy-sync:
  image: node:20
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "main"
    - if: $CI_PIPELINE_SOURCE == "web"
  variables:
    PRISMY_REPO_ID: "YOUR_REPO_ID"
    PRISMY_BUNDLE_NAME: "common"
  before_script:
    - npm install -g prismy-cli
  script:
    - prismy push src/i18n/en.json --repo-id "${PRISMY_REPO_ID}" --language en-US --bundle-name "${PRISMY_BUNDLE_NAME}" --wait-for-translations
    - prismy pull src/i18n/en.json --repo-id "${PRISMY_REPO_ID}" --language en-US --bundle-name "${PRISMY_BUNDLE_NAME}"
    - prismy pull src/i18n/es.json --repo-id "${PRISMY_REPO_ID}" --language es-ES --bundle-name "${PRISMY_BUNDLE_NAME}"
    - prismy pull src/i18n/fr.json --repo-id "${PRISMY_REPO_ID}" --language fr-FR --bundle-name "${PRISMY_BUNDLE_NAME}"
    - |
      git config user.name "GitLab CI"
      git config user.email "ci@gitlab"
      git add src/i18n/
      git diff --staged --quiet || git commit -m "chore(i18n): sync translations from Prismy"
      git push "https://oauth2:${CI_JOB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git" HEAD:${CI_COMMIT_REF_NAME}
```

Add `PRISMY_API_TOKEN` in **Settings → CI/CD → Variables** (masked). Adjust `git push` if you use a deploy token or project access token.

### Bitbucket Pipelines

Use a step that installs the CLI, runs `prismy push` with `--wait-for-translations`, then `prismy pull` for each language, and finally commits and pushes. Set `PRISMY_API_TOKEN`, `PRISMY_REPO_ID`, and `PRISMY_BUNDLE_NAME` as repository variables.

### Run only when i18n changes

* **GitHub Actions**: Under `on.push`, add `paths: ["src/i18n/en.json"]`.
* **GitLab CI**: In `rules`, use `changes: ["src/i18n/en.json"]`.

Adjust paths and branch names to match your project.

Reference: [prismy-cli — PRISMY\_PUSH\_PULL\_CI](https://github.com/TheCompanyX/prismy-cli/blob/main/docs/PRISMY_PUSH_PULL_CI.md), [CI\_SETUP](https://github.com/TheCompanyX/prismy-cli/blob/main/docs/CI_SETUP.md)