Lokex CLI: Content exchange tool for Lokalise

lokex-cli is a focused CLI built specifically for file exchange with Lokalise on top of lokex.

It is intentionally narrow in scope, so you can only upload and download files. This tool is meant to be a fast, optimized workflow for import/export operations.

If you need a broader Lokalise command set, use the official CLI instead.

Installation

There are several ways to install lokex-cli, depending on your environment.

Download prebuilt binaries

Download the latest release for your OS and architecture from the Releases page.

Linux / macOS (install script)

curl -fsSL https://raw.githubusercontent.com/bodrovis/lokex-cli/master/install.sh | sh

Install a specific version:

VERSION=0.2.0 curl -fsSL https://raw.githubusercontent.com/bodrovis/lokex-cli/master/install.sh | sh

Install to a custom directory:

INSTALL_DIR="$HOME/.local/bin" curl -fsSL https://raw.githubusercontent.com/bodrovis/lokex-cli/master/install.sh | sh

Windows (PowerShell)

$script = "$env:TEMP\install-lokex.ps1"
Invoke-WebRequest "https://raw.githubusercontent.com/bodrovis/lokex-cli/master/install.ps1" -OutFile $script
powershell -ExecutionPolicy Bypass -File $script

Install a specific version:

powershell -ExecutionPolicy Bypass -File $script -Version 0.2.0

Install to a custom directory:

powershell -ExecutionPolicy Bypass -File $script -InstallDir "$env:LOCALAPPDATA\Programs\lokex-cli\bin"

GitHub Actions

Install lokex-cli in workflows using the install-lokex-cli action.

Example:

steps:
  - uses: bodrovis/install-lokex-cli@v1
  - run: lokex-cli version

Documentation

Detailed command docs are generated in:

Those files list all supported flags and API-related parameters for each command.

Global flags

These flags are shared by both upload and download.

Find full list of global flags in the docs.

Required in all cases

These two flags are always required:

--token
--project-id

Example:

lokex-cli download \
  --token YOUR_TOKEN \
  --project-id YOUR_PROJECT_ID \
  --format json

Download examples

Basic download

lokex-cli download \
  --token YOUR_TOKEN \
  --project-id YOUR_PROJECT_ID \
  --format json

This downloads files from Lokalise and extracts them into ./locales by default.

Download into a custom directory

lokex-cli download \
  --token YOUR_TOKEN \
  --project-id YOUR_PROJECT_ID \
  --format json \
  --out ./tmp/locales

Async download flow

lokex-cli download \
  --token YOUR_TOKEN \
  --project-id YOUR_PROJECT_ID \
  --format json \
  --async

Download with extra API parameters

lokex-cli download \
  --token YOUR_TOKEN \
  --project-id YOUR_PROJECT_ID \
  --format json \
  --original-filenames \
  --filter-langs en,fr,de \
  --include-tags mobile,release

Upload examples

Basic upload

lokex-cli upload \
  --token YOUR_TOKEN \
  --project-id YOUR_PROJECT_ID \
  --filename locales/en.json \
  --lang-iso en

Upload and wait until processing finishes

lokex-cli upload \
  --token YOUR_TOKEN \
  --project-id YOUR_PROJECT_ID \
  --filename en.json \
  --lang-iso en \
  --poll

Upload with extra import options

lokex-cli upload \
  --token YOUR_TOKEN \
  --project-id YOUR_PROJECT_ID \
  --filename en.json \
  --lang-iso en \
  --replace-modified \
  --convert-placeholders \
  --tags backend,release

Batch upload via manifest

The upload command supports batch uploads using a JSON manifest file:

lokex upload --manifest path/to/manifest.json

When --manifest is provided:

Upload parameters are taken from the manifest file
CLI upload flags (e.g. --filename, --lang-iso, etc.) are ignored
Global options --token and --project-id are still used (and can be read from ENV or YAML file)

Manifest format

The manifest is a JSON file with the following structure:

{
  "items": [
    {
      "params": {
        "filename": "locales/en.json",
        "lang_iso": "en"
      }
    },
    {
      "params": {
        "filename": "locales/%LANG_ISO%.json",
        "lang_iso": "de"
      },
      "src_path": "./de.json"
    }
  ]
}

Fields:

items — list of upload entries

Each item contains:

params (required) — key-value map of upload parameters (same as single upload API)
- Must include at least:
  - filename
  - lang_iso
src_path (optional) — local file path to read file contents from

File resolution

If src_path is provided:
- File contents are read from this path
If src_path is not provided:
- The uploader attempts to read file contents from params.filename

Note on relative raths:

src_path is resolved relative to the directory of the manifest file
Absolute paths are used as-is

Example:

/configs/batch/manifest.json
/configs/batch/de.json

{
  "src_path": "de.json"
}

Will resolve to:

/configs/batch/de.json

Behavior

All uploads are started in parallel (up to parallel 6 requests)
If --poll is enabled:
- The command waits for all uploads to complete
If --poll is disabled:
- The command returns immediately after starting uploads

Output

Each item produces its own result:

Success:
- Upload started or Upload completed
Failure:
- Upload failed with error details

At the end, a summary is printed:

Batch summary: total=N success=X failed=Y

Error handling

Errors are reported per item
The command does not fail on partial errors
Only fatal batch-level errors (e.g. invalid manifest, request failure) cause the command to exit with error

Uploads: `filename` and `src-path`

For most uploads, you only need --filename.

Example:

lokex-cli upload \
  --token YOUR_TOKEN \
  --project-id YOUR_PROJECT_ID \
  --filename ./locales/en.json \
  --lang-iso en

That is totally fine.

If needed, you can also set --src-path explicitly to tell the CLI where to read the local file from, while keeping a different filename for Lokalise:

lokex-cli upload \
  --token YOUR_TOKEN \
  --project-id YOUR_PROJECT_ID \
  --filename en.json \
  --src-path ./locales/en.json \
  --lang-iso en

About data

The upload API supports a data field.

You can pass it with:

--data BASE64_ENCODED_CONTENT

But in normal usage you usually do not need this.

If data is not provided, lokex-cli reads the file from disk and prepares the payload for you automatically.

So the normal upload flow is:

provide --filename
optionally provide --src-path
provide --lang-iso
let the tool read and encode the file itself

Passing arrays and JSON via CLI

Some flags accept arrays (lists of values) or structured JSON. Here is how to pass them in a shell.

String arrays

Flags like --filter-langs, --include-tags, etc. accept multiple values.

You can pass them in two ways:

Comma-separated

lokex-cli download \
  --format=json \
  --filter-langs=en,fr,de \
  --include-tags=mobile,web

Repeated flags

lokex-cli download \
  --format=json \
  --filter-langs=en \
  --filter-langs=fr \
  --filter-langs=de

JSON arrays

Some flags like --language-mapping expect structured JSON (array of objects).

Example:

lokex-cli download \
  --format=json \
  --language-mapping='[
    {"lang_iso":"en","custom_iso":"en_US"},
    {"lang_iso":"pt","custom_iso":"pt_BR"}
  ]'

Important notes:

Always wrap JSON in quotes ('...') to prevent the shell from interpreting it.
On Windows (PowerShell), you may need to use double quotes:

--language-mapping "[{\"lang_iso\":\"en\",\"custom_iso\":\"en_US\"}]"

Configuration via environment variables and YAML

In addition to CLI flags, lokex-cli can also read command defaults from:

environment variables
an optional YAML config file

YAML file

Config file can be provided explicitly:

lokex-cli --config path/to/config.yaml <command>

If --config is not set, lokex-cli will try to automatically find a config file named lokex.yaml in the following locations:

current working directory (./lokex.yaml)
user config directory: ~/.config/lokex-cli/lokex.yaml

If no config file is found, execution continues without error.

Command-specific options must be placed under the matching namespace:

download.* for lokex-cli download
upload.* for lokex-cli upload

Example:

token: token
project-id: project-id

download:
  format: json
  out: ./tmp/locales
  async: true
  filter-langs:
    - en
    - fr
  include-tags:
    - mobile
    - release

upload:
  filename: en.json
  src-path: ./locales/en.json
  lang-iso: en
  poll: true
  replace-modified: true
  tags:
    - backend
    - release

Environment variables

Environment variables follow the same logical keys as the YAML config, using the LOKEX env prefix.

LOKEX_TOKEN=token
LOKEX_PROJECT_ID=project-id
LOKEX_DOWNLOAD_FORMAT=json
LOKEX_DOWNLOAD_OUT=./locales
LOKEX_UPLOAD_FILENAME=en.json
LOKEX_UPLOAD_LANG_ISO=en
LOKEX_UPLOAD_POLL=true

Precedence

If you pass a value explicitly as a CLI flag, it overrides the value from YAML or environment variables.

So the effective order is:

explicit CLI flag
environment variable / YAML config
built-in default

Testing

Run:

go test -count=1 ./... -shuffle=on -race

Release verification

Each release includes extra verification artifacts:

*_checksums.txt — SHA256 checksums for release files
*_checksums.txt.sigstore.json — Cosign signature bundle for the checksum file
*.sbom.json — SBOM files generated for release archives

GitHub Artifact Attestations are available at: github.com/bodrovis/lokex-cli/attestations.

License

(c) Elijah S. Krukowski. Licensed under BSD 3-Clause

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
.github		.github
cmd		cmd
docs		docs
internal		internal
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
LICENSE.md		LICENSE.md
README.md		README.md
go.mod		go.mod
go.sum		go.sum
install.ps1		install.ps1
install.sh		install.sh
main.go		main.go
main_test.go		main_test.go

Folders and files

Latest commit

History

Repository files navigation

Lokex CLI: Content exchange tool for Lokalise

Installation

Download prebuilt binaries

Linux / macOS (install script)

Windows (PowerShell)

GitHub Actions

Documentation

Global flags

Required in all cases

Download examples

Basic download

Download into a custom directory

Async download flow

Download with extra API parameters

Upload examples

Basic upload

Upload and wait until processing finishes

Upload with extra import options

Batch upload via manifest

Manifest format

File resolution

Behavior

Output

Error handling

Uploads: filename and src-path

About data

Passing arrays and JSON via CLI

String arrays

Comma-separated

Repeated flags

JSON arrays

Configuration via environment variables and YAML

YAML file

Environment variables

Precedence

Testing

Release verification

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 4

Uh oh!

Contributors

Uh oh!

Languages

Uploads: `filename` and `src-path`