Langctl Logo langctl
Get Started

CLI Installation

The LangCTL CLI is a powerful command-line tool for managing translations directly from your terminal and CI/CD pipelines.

System Requirements

  • Node.js: 16.x or higher
  • npm: 7.x or higher (or yarn/pnpm)
  • Operating System: macOS, Linux, or Windows
  • Terminal: Any modern terminal with UTF-8 support

Installation Methods

Install globally using npm:

npm install -g @langctl/cli

langctl --version
yarn global add @langctl/cli

langctl --version
pnpm add -g @langctl/cli

langctl --version
💡
Tip

Installing globally allows you to use langctl from any directory. Perfect for CI/CD integration.

Check that the CLI is properly installed:

$ langctl --version
langctl version 1.0.0

$ langctl --help
Usage: langctl [options] [command]

CLI tool for LangCTL translation management

Options:
-V, --version              output the version number
-h, --help                 display help for command

Commands:
auth                       Authentication commands
org                        Organization commands
projects                   Project management
keys                       Translation key management
export                     Export translations
import                     Import translations
help [command]             display help for command

Before using the CLI, create an API key from the dashboard:

  1. Log in to app.langctl.com
  2. Navigate to API Keys section
  3. Click “Generate API Key”
  4. Name it (e.g., “CLI Development”)
  5. Select scopes (start with all permissions)
  6. Copy the key (shown only once!)

[IMAGE: generate-api-key.png - Screenshot of API key generation]

🚨
Important

Save your API key immediately! It’s shown only once and cannot be retrieved later. Store it securely.

Set your API key using the auth command:

langctl auth login
? Enter your API key: lc_abc123...

langctl auth login --key lc_abc123...

langctl auth whoami

The API key is stored securely in ~/.langctlrc.

The CLI stores configuration in:

  • macOS/Linux: ~/.langctlrc
  • Windows: %USERPROFILE%\.langctlrc
Configuration file 
{
"apiKey": "lc_abc123...",
"organizationId": "org_xyz789",
"defaultLanguage": "en"
}

Override config with environment variables:

export LANGCTL_API_KEY="lc_abc123..."

export LANGCTL_API_ENDPOINT="https://your-instance.com"

langctl export my-app -l en
💡
CI/CD Best Practice

Use environment variables in CI/CD instead of checking config files into git. Store API keys as secrets in your CI/CD platform.

Set defaults for a specific project:

cd my-app
langctl init

? Select organization: Acme Corp
? Select project: Mobile App
? Default export format: i18next
? Output directory: ./src/locales
.langctlrc (project-level) 
{
"project": "mobile-app-uuid",
"format": "i18next",
"output_dir": "./src/locales",
"languages": ["en", "es", "fr"],
"module_filter": ["auth", "dashboard"],
"published_only": true
}

Project config takes precedence over global config.

ℹ️
Note

Add .langctlrc to .gitignore if it contains sensitive information. Commit it if it only has project settings.

langctl --version

langctl update --check

npm update -g @langctl/cli

Update Notifications

The CLI automatically checks for updates weekly and notifies you:

╭─────────────────────────────────────────╮
│                                         │
│   Update available: 1.0.0 -> 1.1.0      │
│   Run: npm update -g @langctl/cli      │
│                                         │
│   Changelog:                            │
│   - New: Batch export command          │
│   - Fix: Windows path handling         │
│                                         │
╰─────────────────────────────────────────╯

Uninstalling

Remove CLI

npm uninstall -g @langctl/cli

yarn global remove @langctl/cli

pnpm remove -g @langctl/cli

rm ~/.langctlrc

Troubleshooting

Command Not Found

Error: langctl: command not found

Solutions:

  • Verify installation: npm list -g @langctl/cli
  • Check PATH includes npm global bin: npm bin -g
  • Reinstall CLI
  • Use full path: $(npm bin -g)/langctl

Permission Denied

Error: EACCES: permission denied

Solutions:

# macOS/Linux: Use sudo
sudo npm install -g @langctl/cli

# Or fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile
npm install -g @langctl/cli

Invalid API Key

Error: Authentication failed: Invalid API key

Solutions:

  • Verify key is correct (check for typos)
  • Ensure key hasn’t been revoked
  • Generate new key from dashboard
  • Check ~/.langctlrc format is valid JSON

Network Errors

Error: ENOTFOUND: api.langctl.com

Solutions:

  • Check internet connection
  • Verify firewall allows HTTPS to api.langctl.com
  • Try different network
  • Check company proxy settings

Platform-Specific Notes

Windows

PowerShell:

pwsh
langctl --version

$env:USERPROFILE.langctlrc

Command Prompt:

%APPDATA%
pmlangctl --version

WSL (Windows Subsystem for Linux): Works same as Linux. Install Node.js in WSL environment.

Homebrew (alternative installation):

brew tap langctl/tap

brew install langctl

brew upgrade langctl

Apple Silicon (M1/M2): Node.js must be arm64 version. Check with:

node -p "process.arch"

Snap (alternative installation):

sudo snap install langctl

sudo snap refresh langctl

Docker (isolated installation):

docker run --rm -it -v $(pwd):/workspace langctl/cli:latest

alias langctl='docker run --rm -it -v $(pwd):/workspace langctl/cli:latest'
langctl completion bash > /usr/local/etc/bash_completion.d/langctl

eval "$(langctl completion bash)"
eval "$(langctl completion zsh)"
langctl completion fish > ~/.config/fish/completions/langctl.fish

Next Steps

Now that you’ve installed the CLI: