Getting started

Installation & Setup

Complete guide to setting up langctl for your team, including both the web dashboard and CLI tool.

Prerequisites

Before installing langctl, ensure you have:

For Dashboard

• Modern web browser (Chrome, Firefox, Safari, Edge)
• Valid email address
• Internet connection

For CLI

• Node.js 20 or higher (Download)
• npm or yarn package manager
• Terminal/Command line access
• langctl account (for API key)

Verify Node.js Installation

node --version
npm --version

Set Up the Dashboard

Create Your Account

1. Navigate to app.langctl.com/signup
2. Fill in the form:
   • Full Name: Your name
   • Email: A valid email address (you’ll receive a verification link)
   • Password: At least 8 characters
3. Click Create account

Verify Your Email

After signing up:

1. Check your email inbox
2. Open the verification email from langctl
3. Click the verification link (it expires after 24 hours)
4. You’ll be taken back to the app

Create Your Organization

After verifying your email and signing in:

1. You’ll be asked to create an organization
2. Enter your organization name:
   • Can be your company name, team name, or project name
   • Examples: “Acme Inc”, “My Startup”, “Personal Projects”
3. Create the organization

After creating your organization, you’ll land on Home:

• Sidebar: Projects, the current project’s Translations, Import & Export, Languages and Project settings, plus Team, API Keys, Plan & Billing and Settings
• Getting started checklist: Create a project, add keys, install the CLI, pull translations
• Your projects: Key counts and missing translations per project

To rename the organization later, go to Settings in the sidebar (owners and admins only). Your plan and usage are under Plan & Billing.

Install the CLI

npm install -g langctl

The -g flag installs langctl globally, making it available from any directory.

yarn global add langctl

Run without installing:

npx langctl --version

langctl --version
langctl --help

If you see the version number, installation was successful!

If you get command not found: langctl after npm install:

1. Check npm global bin path:

   npm config get prefix

2. Add to PATH (macOS/Linux):

   export PATH="$PATH:$(npm config get prefix)/bin"

3. Reload shell:

   source ~/.zshrc  # or ~/.bashrc

If you get permission errors:

npx langctl

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g langctl

On Windows, ensure Node.js bin directory is in PATH:

1. Open System Properties -> Environment Variables
2. Edit PATH variable
3. Add: %APPDATA%\\npm
4. Restart terminal

Create an API Key

1. Log in to app.langctl.com
2. Navigate to API Keys in the sidebar
3. Click New API Key
4. Enter a descriptive name:
   • Examples: “My Laptop”, “CI/CD”, “Development”
5. Choose its permissions (see scopes)
6. Click Create API Key
7. Copy the API key immediately (it’s shown only once!)

langctl init

langctl init asks for the API key (input is hidden), lets you pick a project, file format and path, and writes a langctl.json to commit with your code.

To store a key without setting up a repository, use langctl auth. It prompts for the key, or reads it from stdin so the key stays out of your shell history:

langctl auth                              # prompts for the key (input hidden)
echo "$MY_LANGCTL_KEY" | langctl auth --stdin

For CI/CD or temporary use, set an environment variable instead — no login step needed:

export LANGCTL_API_KEY=lc_your_api_key_here
langctl projects list

Check that everything works:

langctl whoami

whoami shows your organization, where the key came from, its scopes and the API latency. If you see your organization, authentication was successful!

The stored key lives in ~/.langctl/config.json (readable only by you, mode 600; set LANGCTL_CONFIG_DIR to move it). LANGCTL_API_KEY and --api-key take precedence over it. Project settings (project, format, output path) live in langctl.json in your repository instead.

To see the effective configuration and where each value comes from:

langctl config

To remove the stored key:

langctl logout

To switch between organizations or environments:

LANGCTL_API_KEY=lc_prod_key_here langctl pull

LANGCTL_API_KEY=lc_dev_key_here langctl push --dry-run

✅ DO:

• Store API keys in environment variables for CI/CD
• Use separate API keys for different environments
• Revoke unused API keys
• Rotate keys periodically (every 90 days)
• Use descriptive names to track key usage

❌ DON’T:

• Commit API keys to version control
• Share API keys via email or chat
• Use production keys in development
• Store keys in plain text files in your repository

# .gitignore — keep keys out of the repo
.env

# .env
LANGCTL_API_KEY=lc_your_key_here

# load it in your shell
export LANGCTL_API_KEY=$(grep LANGCTL_API_KEY .env | cut -d '=' -f2)

langctl.json contains no secrets (only project, format and paths), so commit it.

Use secrets management:

• GitHub Actions: Use repository secrets
• GitLab CI: Use CI/CD variables
• CircleCI: Use environment variables
• Jenkins: Use credentials plugin

- name: Check translations are up to date
env:
  LANGCTL_API_KEY: ${{ secrets.LANGCTL_API_KEY }}
run: npx langctl@0 pull --check

Invite Your Team

1. Navigate to Team in the sidebar
2. Enter one or more email addresses (separate several with commas)
3. Select a role:
   • Admin: Projects, keys, import/export, team members and API keys
   • Member: Edit translations and keys, import and export
   • Viewer: Read-only access to projects and translations
4. Click Send Invite

Owners and admins can invite people. Your plan’s member limit applies - the Free plan has a single seat, so inviting teammates needs a plan with more members.

langctl team invite developer@company.com --role member
langctl team invite manager@company.com --role admin

Team commands need an API key with the org:admin scope.

1. The team member receives an invitation email (valid for 7 days)
2. They click the invitation link
3. They create an account (if new) or sign in with the invited email address
4. They’re added to the organization and can access every project, according to their role

Now that you’re set up, continue with:

• Dashboard Overview - Learn the web interface
• CLI Reference - Master CLI commands
• Quick Start - Create your first project
• Platform Integrations - Integrate with your framework

If you need to uninstall langctl:

npm uninstall -g langctl

yarn global remove langctl

rm -rf ~/.langctl   # stored API key and CLI configuration

Delete Your Organization

1. Log in to the dashboard
2. Go to Settings in the sidebar
3. Scroll to Danger Zone
4. Click Delete Organization (owners only)
5. Type the organization name to confirm