npm package: @locely/cli
Description: Command line utility for Locely - Synchronize translations with ease
Latest version: 1.0.0

# Locely CLI

Command-line tool for synchronizing translations with [Locely](https://locely.xyz), a localization management platform.

For full documentation, visit [https://locely.xyz/docs](https://locely.xyz/docs).

## Installation

```bash
npm install -g @locely/cli
```

Or use with `npx`:

```bash
npx @locely/cli login
```

## Quick Start

### 1. Authenticate

First, authenticate with your Locely instance:

```bash
locely login
```

You'll be prompted to enter your API token. You can create a token in:
- **Project Settings > API Tokens** (for project-specific access)
- **Profile > Access Tokens** (for full user access)

By default, the CLI connects to `https://locely.xyz`. The `/api` path is automatically appended. To use a different instance (e.g., self-hosted):

```bash
locely login --url https://your-locely-instance.com
```

You can also provide the full URL with `/api` if you prefer:
```bash
locely login --url https://your-locely-instance.com/api
```

### 2. Push Translations

Upload local translation files to Locely:

```bash
locely push --project PROJECT_ID --files "./locales/*.json"
```

The CLI will:
- Find all files matching the glob pattern
- Infer the language code from the filename (e.g., `en.json` → `en`, `translation.fr.json` → `fr`)
- Flatten nested JSON objects
- Upload each file to the specified project

**Example:**
```bash
locely push -p abc123 -f "./src/locales/**/*.json"
```

### 3. Pull Translations

Download translations from Locely:

```bash
locely pull --project PROJECT_ID --output ./locales
```

**Options:**
- `--format <type>` - Output format (default: `json_flat`)
  - Available formats: `json_flat`, `android_xml`, `ios_strings`, etc.
- `--languages <codes>` - Comma-separated list of language codes (default: all languages)

**Examples:**
```bash
# Download all languages as JSON
locely pull -p abc123 -o ./locales

# Download specific languages in Android XML format
locely pull -p abc123 -o ./android/res --format android_xml --languages en,es,fr

# Download iOS strings format
locely pull -p abc123 -o ./ios/Localizations --format ios_strings
```

## Commands

### `login`

Authenticate with Locely using an API token.

```bash
locely login [--url <url>]
```

**Options:**
- `--url <url>` - Base URL of the Locely instance (default: `https://locely.xyz`). The `/api` path is automatically appended if not present.

### `push`

Upload local translation files to Locely.

```bash
locely push --project <id> --files <pattern>
```

**Required Options:**
- `-p, --project <id>` - Locely Project ID
- `-f, --files <pattern>` - Glob pattern for translation files (e.g., `"./locales/*.json"`)

**How it works:**
- The CLI searches for files matching the glob pattern
- Language codes are inferred from filenames:
  - `en.json` → language code: `en`
  - `translation.fr.json` → language code: `fr`
  - `en-US.json` → language code: `en-US`
- Nested JSON objects are automatically flattened (e.g., `{ "auth": { "login": "Log In" } }` → `{ "auth.login": "Log In" }`)

### `pull`

Download translations from Locely.

```bash
locely pull --project <id> --output <dir> [--format <type>] [--languages <codes>]
```

**Required Options:**
- `-p, --project <id>` - Locely Project ID
- `-o, --output <dir>` - Output directory for translation files (default: `./locales`)

**Optional Options:**
- `--format <type>` - Output file format (default: `json_flat`)
  - Supported formats: `json_flat`, `android_xml`, `ios_strings`, and more
- `--languages <codes>` - Comma-separated list of language codes to export (default: all languages)

## Configuration

The CLI stores your authentication token and API URL in your system's configuration directory:
- **macOS**: `~/Library/Preferences/@locely/cli/config.json`
- **Linux**: `~/.config/@locely/cli/config.json`
- **Windows**: `%APPDATA%\@locely\cli\config.json`

## CI/CD Integration

The CLI is perfect for CI/CD pipelines. Here's an example GitHub Actions workflow:

```yaml
name: Sync Translations

on:
  push:
    branches: [main]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install Locely CLI
        run: npm install -g @locely/cli
      
      - name: Login to Locely
        run: |
          echo "${{ secrets.LOCELY_API_TOKEN }}" | locely login --url ${{ secrets.LOCELY_API_URL }}
      
      - name: Pull Translations
        run: locely pull -p ${{ secrets.LOCELY_PROJECT_ID }} -o ./locales
      
      - name: Commit and Push
        run: |
          git config user.name "github-actions"
          git config user.email "github-actions@github.com"
          git add ./locales
          git commit -m "Update translations" || exit 0
          git push
```

**Environment Variables:**
- `LOCELY_API_TOKEN` - Your API token
- `LOCELY_API_URL` - Your Locely instance URL (optional, defaults to https://locely.xyz). The `/api` path is automatically appended if not present.
- `LOCELY_PROJECT_ID` - Your project ID

## Supported Formats

The `pull` command supports multiple export formats:

- **json_flat** - Flat JSON format (default)
- **android_xml** - Android `strings.xml` format
- **ios_strings** - iOS `.strings` format
- And more (check your Locely instance for available formats)

## Requirements

- Node.js >= 18.0.0
- A Locely instance (self-hosted or cloud)

## Troubleshooting

### "Authentication failed"
- Verify your API token is correct
- Check that the API URL is correct (use `--url` flag if needed)
- Ensure your token hasn't expired

### "No files found matching pattern"
- Check that your glob pattern is correct
- Use quotes around patterns with wildcards: `"./locales/*.json"`
- Verify the files exist in the expected location

### "Project not found"
- Verify the project ID is correct
- Ensure your API token has access to the project

## License

MIT

## Links

- [Locely Website](https://locely.xyz)
- [Locely Documentation](https://locely.xyz/docs)