langctl 0.1.0 → 0.1.2

package/README.md

@@ -2,7 +2,18 @@
 
 > CLI-first translation management for developers
 
-Langctl is a command-line tool that lets you manage translations directly from your terminal. Pull translations in multiple formats, sync with your projects, and integrate seamlessly into your CI/CD pipeline.
+Langctl is a powerful command-line tool that lets you manage translations directly from your terminal. Create projects, manage translation keys, invite team members, export in multiple formats, and integrate seamlessly into your CI/CD pipeline.
+
+## Features
+
+- 🚀 **Complete Project Management** - Create, update, and manage translation projects
+- 🔑 **Translation Key CRUD** - Full control over translation keys and values
+- 👥 **Team Management** - Invite members, manage roles, and handle invitations
+- 📊 **Organization Insights** - View stats, plan limits, and usage metrics
+- 📦 **Multi-Format Export** - Support for JSON, iOS, Android, Flutter, and i18n
+- 🔄 **Import Translations** - Bulk import from JSON files
+- 🤖 **CI/CD Ready** - Perfect for automated workflows
+- 🌍 **Multi-Language Support** - Manage unlimited languages per project
 
 ## Installation
 
@@ -10,7 +21,7 @@ Langctl is a command-line tool that lets you manage translations directly from y
 npm install -g langctl
 ```
 
-Or use with npx:
+Or use with npx (no installation required):
 
 ```bash
 npx langctl --help
@@ -18,170 +29,784 @@ npx langctl --help
 
 ## Quick Start
 
-### 1. Initialize Configuration
+### 1. Get Your API Key
+
+1. Visit [app.langctl.com](https://app.langctl.com) and sign in
+2. Go to **Settings → API Keys**
+3. Click **"Generate New Key"**
+4. Copy the key (it's only shown once!)
 
-Run the interactive setup wizard to configure Langctl:
+### 2. Authenticate
 
 ```bash
+# Interactive setup
 langctl init
+
+# Or authenticate directly
+langctl auth lc_your_api_key_here
 ```
 
-This will:
-- Configure Supabase connection (uses defaults)
-- Authenticate with your API key (get one from the dashboard)
-- Set your default language preference
+### 3. Explore Your Organization
 
-### 2. List Your Projects
+```bash
+# View organization info
+langctl org info
 
-View all projects you have access to:
+# Check statistics
+langctl org stats
 
-```bash
+# List your projects
 langctl projects list
 ```
 
-### 3. Pull Translations
-
-Download translations for a project:
+### 4. Start Working with Translations
 
 ```bash
-langctl pull <project-id> --language en --format json
+# List translation keys
+langctl keys list my-project
+
+# Export translations
+langctl export my-project --language en --format json
+
+# Create a new key
+langctl keys create my-project home.welcome \
+  --value-en "Welcome!" \
+  --value-es "¡Bienvenido!"
 ```
 
-## Commands
+---
+
+## Commands Overview
+
+### Authentication
+- `langctl init` - Interactive setup wizard
+- `langctl auth <api-key>` - Authenticate with API key
+- `langctl logout` - Clear credentials
+- `langctl config` - View current configuration
+
+### Organization
+- `langctl org info` - View organization details
+- `langctl org stats` - View organization statistics
+- `langctl org plan` - View subscription plan and limits
 
-### `langctl init`
+### Projects
+- `langctl projects list` - List all projects
+- `langctl projects create <name>` - Create new project
+- `langctl projects get <slug>` - Get project details
+- `langctl projects update <slug>` - Update project
+- `langctl projects delete <slug>` - Delete project
+- `langctl projects add-language <slug> <language>` - Add language
+- `langctl projects remove-language <slug> <language>` - Remove language
+- `langctl projects stats <slug>` - View project statistics
 
-Interactive setup wizard to configure the CLI.
+### Translation Keys
+- `langctl keys list <project>` - List translation keys
+- `langctl keys get <project> <key>` - Get key details
+- `langctl keys create <project> <key>` - Create new key
+- `langctl keys delete <project> <key>` - Delete key
+- `langctl keys translate <project> <key>` - Update translation
+- `langctl keys publish <project> <keys...>` - Publish/unpublish keys
+
+### Team
+- `langctl team list` - List team members
+- `langctl team get <email>` - Get member details
+- `langctl team invite <email>` - Invite team member
+- `langctl team remove <email>` - Remove team member
+- `langctl team update-role <email> <role>` - Update member role
+- `langctl team invitations` - List invitations
+- `langctl team revoke-invitation <email>` - Revoke invitation
+
+### Import/Export
+- `langctl export <project>` - Export translations
+- `langctl import <project> <file>` - Import translations
+
+---
+
+## Detailed Command Reference
+
+### Authentication Commands
+
+#### `langctl init`
+
+Interactive setup wizard that guides you through authentication and configuration.
 
 ```bash
 langctl init
 ```
 
-### `langctl auth <api-key>`
+#### `langctl auth <api-key>`
 
-Authenticate with an API key from the dashboard.
+Authenticate with an API key from your dashboard.
 
 ```bash
 langctl auth lc_abc123...
 ```
 
-### `langctl logout`
+#### `langctl logout`
 
-Clear authentication credentials.
+Clear stored authentication credentials.
 
 ```bash
 langctl logout
 ```
 
-### `langctl config`
+#### `langctl config`
 
-View current configuration.
+Display current configuration (API key, organization, etc.).
 
 ```bash
 langctl config
 ```
 
-### `langctl projects list`
+---
+
+### Organization Commands
+
+#### `langctl org info`
 
-Show all accessible projects.
+View your organization details.
+
+```bash
+langctl org info
+```
+
+**Output:**
+- Organization name and ID
+- Slug
+- Subscription plan
+- Creation date
+
+#### `langctl org stats`
+
+View comprehensive organization statistics.
+
+```bash
+langctl org stats
+```
+
+**Output:**
+- Total team members
+- Number of projects
+- Translation key counts (total, published, unpublished)
+- Languages used across projects
+- API keys and webhooks
+
+#### `langctl org plan`
+
+View subscription plan details and resource limits.
+
+```bash
+langctl org plan
+```
+
+**Output:**
+- Current plan (Free, Pro, Team, Enterprise)
+- Max members allowed
+- Max projects allowed
+- Max keys per project
+- Max API keys allowed
+
+---
+
+### Project Management Commands
+
+#### `langctl projects list`
+
+List all projects you have access to.
 
 ```bash
 langctl projects list
 ```
 
-### `langctl pull <project-id>`
+**Output:**
+- Project name and slug
+- Description
+- Supported languages
+- Default language
+- Available modules
+
+#### `langctl projects create <name>`
+
+Create a new translation project.
+
+```bash
+langctl projects create "Mobile App" \
+  --description "iOS and Android translations" \
+  --languages en,es,fr,de \
+  --default-language en
+```
+
+**Options:**
+- `-d, --description <text>` - Project description
+- `-l, --languages <langs>` - Comma-separated language codes (default: `en`)
+- `--default-language <code>` - Default language (default: first language)
+
+**Examples:**
+
+```bash
+# Simple project with English only
+langctl projects create "My App"
+
+# Multi-language project
+langctl projects create "Global App" \
+  -l en,es,fr,de,ja \
+  --default-language en
+
+# With description
+langctl projects create "Mobile App" \
+  -d "Translation keys for mobile application" \
+  -l en,es
+```
+
+#### `langctl projects get <slug>`
+
+Get detailed information about a specific project.
+
+```bash
+langctl projects get my-app
+```
+
+**Output:**
+- Project name, ID, and slug
+- Description
+- All supported languages
+- Default language
+- List of modules
+
+#### `langctl projects update <slug>`
+
+Update project details.
+
+```bash
+langctl projects update my-app \
+  --name "New Name" \
+  --description "Updated description" \
+  --languages en,es,fr,de,ja \
+  --default-language en
+```
+
+**Options:**
+- `-n, --name <name>` - Update project name
+- `-d, --description <text>` - Update description
+- `-l, --languages <langs>` - Update supported languages
+- `--default-language <code>` - Update default language
+
+**Examples:**
+
+```bash
+# Change project name
+langctl projects update my-app --name "Better Name"
+
+# Add more languages
+langctl projects update my-app -l en,es,fr,de,ja,zh
+
+# Update description only
+langctl projects update my-app -d "New project description"
+```
+
+#### `langctl projects delete <slug>`
+
+Delete a project (soft delete - can be recovered).
+
+```bash
+langctl projects delete my-app
+```
+
+**Warning:** This will mark the project as deleted. Contact support to recover deleted projects.
+
+#### `langctl projects add-language <slug> <language>`
+
+Add a new language to an existing project.
+
+```bash
+langctl projects add-language my-app de
+```
+
+**Examples:**
+
+```bash
+# Add German
+langctl projects add-language my-app de
+
+# Add Japanese
+langctl projects add-language my-app ja
+
+# Add Chinese
+langctl projects add-language my-app zh
+```
+
+#### `langctl projects remove-language <slug> <language>`
+
+Remove a language from a project.
+
+```bash
+langctl projects remove-language my-app de
+```
+
+**Note:** Cannot remove the default language. Change default language first if needed.
+
+#### `langctl projects stats <slug>`
 
-Pull translations from a project.
+View project statistics.
 
 ```bash
-langctl pull <project-id> [options]
+langctl projects stats my-app
+```
+
+**Output:**
+- Total translation keys
+- Published vs unpublished counts
+- Number of modules
+- List of module names
+
+---
+
+### Translation Key Commands
+
+#### `langctl keys list <project>`
+
+List translation keys for a project.
+
+```bash
+langctl keys list my-app
 ```
 
 **Options:**
+- `-m, --module <name>` - Filter by module
+- `-p, --published` - Show only published keys
+- `-s, --search <term>` - Search in key names
+- `--limit <number>` - Limit results (default: 100)
+- `--offset <number>` - Offset for pagination (default: 0)
+
+**Examples:**
+
+```bash
+# List all keys
+langctl keys list my-app
+
+# Filter by module
+langctl keys list my-app --module auth
+
+# Show only published keys
+langctl keys list my-app --published
 
-- `-l, --language <code>` - Language code to pull (default: en)
-- `-f, --format <type>` - Export format (default: json)
-  - `json` - Flat JSON (key-value pairs)
-  - `json-nested` - Nested JSON (organized by key structure)
-  - `ios` - iOS .strings format
-  - `android` - Android XML format
-  - `flutter` - Flutter ARB format
-- `-o, --output <path>` - Output file path (default: ./translations/<filename>)
-- `--no-published-only` - Include unpublished translations
+# Search for specific keys
+langctl keys list my-app --search "welcome"
+
+# Pagination
+langctl keys list my-app --limit 50 --offset 0
+langctl keys list my-app --limit 50 --offset 50
+```
+
+#### `langctl keys get <project> <key>`
+
+Get detailed information about a specific translation key.
+
+```bash
+langctl keys get my-app home.welcome
+```
+
+**Output:**
+- Key name and ID
+- Description
+- Module
+- Published status
+- All translations for all languages
+
+#### `langctl keys create <project> <key>`
+
+Create a new translation key with values for multiple languages.
+
+```bash
+langctl keys create my-app home.welcome \
+  --description "Welcome message on homepage" \
+  --module home \
+  --value-en "Welcome to our app!" \
+  --value-es "¡Bienvenido a nuestra aplicación!" \
+  --value-fr "Bienvenue dans notre application!" \
+  --value-de "Willkommen in unserer App!"
+```
+
+**Options:**
+- `-d, --description <text>` - Key description
+- `-m, --module <name>` - Module/namespace for organization
+- `--value-en <value>` - English translation
+- `--value-es <value>` - Spanish translation
+- `--value-fr <value>` - French translation
+- `--value-de <value>` - German translation
+- `--tags <tags>` - Comma-separated tags
+
+**Supported language options:**
+You can use `--value-{language}` for any language code in your project.
 
 **Examples:**
 
 ```bash
-# Pull English translations as JSON
-langctl pull abc-123 --language en --format json
+# Simple key with one language
+langctl keys create my-app button.submit --value-en "Submit"
+
+# Multi-language key
+langctl keys create my-app home.title \
+  --module home \
+  --value-en "Home" \
+  --value-es "Inicio" \
+  --value-fr "Accueil"
+
+# With description and tags
+langctl keys create my-app error.network \
+  --description "Network connection error" \
+  --module errors \
+  --value-en "Network error occurred" \
+  --tags error,network
+```
 
-# Pull Spanish translations as iOS strings
-langctl pull abc-123 --language es --format ios
+#### `langctl keys delete <project> <key>`
 
-# Pull all translations (including unpublished)
-langctl pull abc-123 --language en --no-published-only
+Delete a translation key.
 
-# Custom output path
-langctl pull abc-123 --language en --output ./locales/en.json
+```bash
+langctl keys delete my-app home.welcome
 ```
 
-## Export Formats
+#### `langctl keys translate <project> <key>`
 
-### JSON (Flat)
+Update the translation value for a specific language.
 
-Simple key-value pairs with dot notation.
+```bash
+langctl keys translate my-app home.welcome \
+  --language es \
+  --value "¡Bienvenido!"
+```
+
+**Options:**
+- `-l, --language <code>` - Language code (required)
+- `-v, --value <text>` - Translation value (required)
+
+**Examples:**
+
+```bash
+# Update Spanish translation
+langctl keys translate my-app home.title -l es -v "Inicio"
+
+# Update French translation
+langctl keys translate my-app button.submit -l fr -v "Soumettre"
+
+# Add translation for new language
+langctl keys translate my-app home.welcome -l de -v "Willkommen"
+```
+
+#### `langctl keys publish <project> <keys...>`
+
+Publish or unpublish translation keys.
+
+```bash
+# Publish keys
+langctl keys publish my-app home.welcome home.title button.submit
+
+# Unpublish keys
+langctl keys publish my-app home.welcome --unpublish
+```
+
+**Options:**
+- `--unpublish` - Unpublish instead of publish
+
+**Examples:**
+
+```bash
+# Publish single key
+langctl keys publish my-app home.welcome
+
+# Publish multiple keys
+langctl keys publish my-app home.welcome home.title home.subtitle
+
+# Unpublish keys
+langctl keys publish my-app test.key --unpublish
+```
+
+---
+
+### Team Management Commands
+
+#### `langctl team list`
+
+List all team members in your organization.
+
+```bash
+langctl team list
+```
+
+**Output:**
+- Member email
+- Role (viewer, member, admin, owner)
+- Join date
+
+#### `langctl team get <email>`
+
+Get details about a specific team member.
+
+```bash
+langctl team get user@example.com
+```
+
+#### `langctl team invite <email>`
+
+Invite a new team member.
+
+```bash
+langctl team invite user@example.com --role member
+```
+
+**Options:**
+- `-r, --role <role>` - Member role (default: `member`)
+  - `viewer` - Read-only access
+  - `member` - Can manage translations
+  - `admin` - Full project and team management
+
+**Examples:**
+
+```bash
+# Invite as member (default)
+langctl team invite user@example.com
+
+# Invite as admin
+langctl team invite admin@example.com --role admin
+
+# Invite as viewer
+langctl team invite viewer@example.com --role viewer
+```
+
+#### `langctl team remove <email>`
+
+Remove a team member from your organization.
+
+```bash
+langctl team remove user@example.com
+```
+
+**Note:** Cannot remove the organization owner. Cannot remove yourself (use appropriate UI for that).
+
+#### `langctl team update-role <email> <role>`
+
+Update a team member's role.
+
+```bash
+langctl team update-role user@example.com admin
+```
+
+**Valid roles:** `viewer`, `member`, `admin`
+
+**Examples:**
+
+```bash
+# Promote to admin
+langctl team update-role user@example.com admin
+
+# Demote to viewer
+langctl team update-role user@example.com viewer
+```
+
+#### `langctl team invitations`
+
+List all invitations (pending, accepted, or cancelled).
+
+```bash
+# List all invitations
+langctl team invitations
+
+# List only pending invitations
+langctl team invitations --pending
+```
+
+**Options:**
+- `-p, --pending` - Show only pending invitations
+
+#### `langctl team revoke-invitation <email>`
+
+Revoke a pending invitation.
+
+```bash
+langctl team revoke-invitation user@example.com
+```
+
+---
+
+### Export/Import Commands
+
+#### `langctl export <project>`
+
+Export translations in various formats.
+
+```bash
+langctl export my-app --language en --format flat-json
+```
+
+**Options:**
+- `-l, --language <code>` - Language to export (default: exports all languages)
+- `-f, --format <type>` - Export format (default: `flat-json`)
+- `-o, --output <path>` - Output file path (optional)
+- `-m, --module <name>` - Export only specific module
+- `--include-unpublished` - Include unpublished keys (default: published only)
+
+**Supported formats:**
+- `flat-json` - Flat key-value JSON (default)
+- `nested-json` - Nested JSON structure
+- `i18n-json` - i18next compatible format
+- `android-xml` - Android strings.xml format
+- `ios-strings` - iOS Localizable.strings format
+- `flutter-arb` - Flutter ARB format
+
+**Examples:**
+
+```bash
+# Export single language as JSON
+langctl export my-app -l en -f flat-json
+
+# Export all languages
+langctl export my-app
+
+# Export for iOS
+langctl export my-app -l en -f ios-strings -o ./ios/en.lproj/Localizable.strings
+
+# Export for Android
+langctl export my-app -l es -f android-xml -o ./android/res/values-es/strings.xml
+
+# Export for Flutter
+langctl export my-app -l fr -f flutter-arb -o ./lib/l10n/app_fr.arb
+
+# Export specific module
+langctl export my-app -l en --module auth
+
+# Include unpublished translations
+langctl export my-app -l en --include-unpublished
+```
+
+#### `langctl import <project> <file>`
+
+Import translations from a JSON file.
+
+```bash
+langctl import my-app translations.json --language en
+```
+
+**Options:**
+- `-l, --language <code>` - Target language (required)
+- `--overwrite` - Overwrite existing translations
+- `--publish` - Auto-publish imported keys
+
+**Examples:**
+
+```bash
+# Import English translations
+langctl import my-app en.json -l en
+
+# Import and overwrite existing
+langctl import my-app en.json -l en --overwrite
+
+# Import and auto-publish
+langctl import my-app en.json -l en --publish
+
+# Import multiple languages
+langctl import my-app en.json -l en --publish
+langctl import my-app es.json -l es --publish
+langctl import my-app fr.json -l fr --publish
+```
+
+**Supported JSON formats:**
 
 ```json
+// Flat format (recommended)
 {
   "home.welcome": "Welcome!",
-  "home.subtitle": "Get started with {{appName}}"
+  "home.subtitle": "Get started",
+  "button.submit": "Submit"
+}
+
+// Nested format (auto-flattened)
+{
+  "home": {
+    "welcome": "Welcome!",
+    "subtitle": "Get started"
+  },
+  "button": {
+    "submit": "Submit"
+  }
 }
 ```
 
-### JSON (Nested)
+---
 
-Organized by key structure.
+## Export Format Examples
+
+### Flat JSON (Default)
+
+```json
+{
+  "home.welcome": "Welcome!",
+  "home.subtitle": "Get started with {{appName}}",
+  "button.submit": "Submit"
+}
+```
+
+### Nested JSON
 
 ```json
 {
   "home": {
     "welcome": "Welcome!",
     "subtitle": "Get started with {{appName}}"
+  },
+  "button": {
+    "submit": "Submit"
   }
 }
 ```
 
-### iOS Strings
+### i18next JSON
 
-Standard iOS .strings format.
+```json
+{
+  "home": {
+    "welcome": "Welcome!",
+    "subtitle": "Get started with {{appName}}"
+  }
+}
+```
+
+### iOS Strings
 
 ```
+/* Welcome message */
 "home.welcome" = "Welcome!";
-"home.subtitle" = "Get started with %1$@";
+
+/* Homepage subtitle with app name placeholder */
+"home.subtitle" = "Get started with %@";
 ```
 
 ### Android XML
 
-Android resources XML format.
-
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
 <resources>
+  <!-- Welcome message -->
   <string name="home.welcome">Welcome!</string>
+
+  <!-- Homepage subtitle with app name placeholder -->
   <string name="home.subtitle">Get started with %1$s</string>
 </resources>
 ```
 
 ### Flutter ARB
 
-Application Resource Bundle format for Flutter.
-
 ```json
 {
   "@@locale": "en",
   "home.welcome": "Welcome!",
+  "@home.welcome": {
+    "description": "Welcome message"
+  },
   "home.subtitle": "Get started with {appName}",
   "@home.subtitle": {
+    "description": "Homepage subtitle",
     "placeholders": {
       "appName": {
         "type": "String"
@@ -191,36 +816,101 @@ Application Resource Bundle format for Flutter.
 }
 ```
 
-## Configuration
+---
 
-Configuration is stored in `~/.langctl/config.json`:
+## Real-World Workflows
 
-```json
-{
-  "supabaseUrl": "https://xxx.supabase.co",
-  "supabaseAnonKey": "eyJ...",
-  "apiKey": "lc_...",
-  "organizationId": "uuid",
-  "organizationName": "Company Name",
-  "defaultProject": "uuid",
-  "defaultLanguage": "en"
-}
+### Complete Project Setup
+
+```bash
+# 1. Authenticate
+langctl auth lc_your_api_key_here
+
+# 2. Create project
+langctl projects create "Mobile App" \
+  -l en,es,fr,de \
+  --default-language en \
+  -d "iOS and Android application"
+
+# 3. Add translation keys
+langctl keys create mobile-app home.welcome \
+  --module home \
+  --value-en "Welcome!" \
+  --value-es "¡Bienvenido!" \
+  --value-fr "Bienvenue!"
+
+langctl keys create mobile-app button.submit \
+  --module common \
+  --value-en "Submit" \
+  --value-es "Enviar" \
+  --value-fr "Soumettre"
+
+# 4. Publish keys
+langctl keys publish mobile-app home.welcome button.submit
+
+# 5. Export for platforms
+langctl export mobile-app -l en -f ios-strings -o ./ios/en.lproj/
+langctl export mobile-app -l en -f android-xml -o ./android/res/values/
+```
+
+### Bulk Import Workflow
+
+```bash
+# 1. Prepare JSON files (en.json, es.json, fr.json)
+# 2. Import all languages
+langctl import my-app en.json -l en --publish
+langctl import my-app es.json -l es --publish
+langctl import my-app fr.json -l fr --publish
+
+# 3. Verify imports
+langctl keys list my-app --published
+langctl projects stats my-app
+```
+
+### Team Collaboration
+
+```bash
+# 1. Invite team members
+langctl team invite developer@example.com --role member
+langctl team invite manager@example.com --role admin
+
+# 2. Check invitations
+langctl team invitations --pending
+
+# 3. Manage roles
+langctl team update-role developer@example.com admin
+
+# 4. View team
+langctl team list
 ```
 
-## API Keys
+### Multi-Platform Export
 
-Generate API keys from the Langctl dashboard:
+```bash
+# Export for all platforms
+PROJECT="my-app"
+LANG="en"
+
+# Web (i18next)
+langctl export $PROJECT -l $LANG -f i18n-json -o ./src/locales/$LANG.json
+
+# iOS
+langctl export $PROJECT -l $LANG -f ios-strings -o ./ios/$LANG.lproj/Localizable.strings
 
-1. Go to Settings → API Keys
-2. Click "Generate New Key"
-3. Copy the key (shown only once)
-4. Use it with `langctl auth <key>` or `langctl init`
+# Android
+langctl export $PROJECT -l $LANG -f android-xml -o ./android/res/values/strings.xml
+
+# Flutter
+langctl export $PROJECT -l $LANG -f flutter-arb -o ./lib/l10n/app_$LANG.arb
+```
 
-API keys are organization-scoped and provide access to all projects within that organization.
+---
 
 ## CI/CD Integration
 
-Example GitHub Actions workflow:
+### GitHub Actions
+
+Automated translation sync workflow:
 
 ```yaml
 name: Sync Translations
@@ -228,10 +918,10 @@ name: Sync Translations
 on:
   schedule:
     - cron: '0 0 * * *' # Daily at midnight
-  workflow_dispatch:
+  workflow_dispatch: # Manual trigger
 
 jobs:
-  sync:
+  sync-translations:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -244,69 +934,258 @@ jobs:
       - name: Install Langctl
         run: npm install -g langctl
 
-      - name: Configure Langctl
+      - name: Authenticate
         env:
           LANGCTL_API_KEY: ${{ secrets.LANGCTL_API_KEY }}
         run: langctl auth $LANGCTL_API_KEY
 
-      - name: Pull Translations
+      - name: Export Translations
         run: |
-          langctl pull ${{ secrets.PROJECT_ID }} --language en --format json
-          langctl pull ${{ secrets.PROJECT_ID }} --language es --format json
+          langctl export my-project -l en -f i18n-json -o ./locales/en.json
+          langctl export my-project -l es -f i18n-json -o ./locales/es.json
+          langctl export my-project -l fr -f i18n-json -o ./locales/fr.json
 
       - name: Commit Changes
         run: |
-          git config --global user.name "Langctl Bot"
-          git config --global user.email "bot@langctl.com"
-          git add translations/
-          git commit -m "chore: update translations" || echo "No changes"
+          git config user.name "Langctl Bot"
+          git config user.email "bot@langctl.com"
+          git add locales/
+          git diff --staged --quiet || git commit -m "chore: update translations [skip ci]"
           git push
 ```
 
-## Troubleshooting
+### GitLab CI
+
+```yaml
+sync-translations:
+  image: node:18
+  script:
+    - npm install -g langctl
+    - langctl auth $LANGCTL_API_KEY
+    - langctl export my-project -l en -f json -o ./locales/en.json
+    - langctl export my-project -l es -f json -o ./locales/es.json
+    - git config user.name "Langctl Bot"
+    - git config user.email "bot@langctl.com"
+    - git add locales/
+    - git diff --staged --quiet || git commit -m "chore: update translations"
+    - git push origin $CI_COMMIT_BRANCH
+  only:
+    - schedules
+```
+
+### Docker
+
+```dockerfile
+FROM node:18-alpine
+
+RUN npm install -g langctl
+
+WORKDIR /app
+
+COPY . .
+
+# Set API key via environment variable
+ENV LANGCTL_API_KEY=""
 
-### "Not authenticated" error
+# Example: Export translations on build
+RUN langctl auth $LANGCTL_API_KEY && \
+    langctl export my-project -l en -f json -o ./public/locales/en.json
+```
+
+---
+
+## Best Practices
+
+### Project Organization
+
+1. **Use modules** to organize keys by feature:
+   ```bash
+   langctl keys create app auth.login.title --module auth
+   langctl keys create app home.hero.title --module home
+   langctl keys create app settings.profile.name --module settings
+   ```
+
+2. **Follow naming conventions**:
+   ```
+   module.screen.element
+   auth.login.title
+   home.hero.subtitle
+   ```
+
+3. **Add descriptions** to keys:
+   ```bash
+   langctl keys create app button.submit \
+     --description "Primary action button across the app" \
+     --value-en "Submit"
+   ```
+
+### Translation Workflow
+
+1. **Create keys unpublished** (draft mode)
+2. **Add translations** for all languages
+3. **Review and test** translations
+4. **Publish** when ready:
+   ```bash
+   langctl keys publish my-app key1 key2 key3
+   ```
+
+5. **Export** published translations only:
+   ```bash
+   langctl export my-app -l en
+   ```
+
+### Team Management
 
-Run `langctl auth <api-key>` or `langctl init` to authenticate.
+1. **Use appropriate roles**:
+   - `viewer` - Stakeholders, reviewers (read-only)
+   - `member` - Translators, content writers
+   - `admin` - Project managers, team leads
 
-### "Supabase not configured" error
+2. **Regular access reviews**:
+   ```bash
+   langctl team list
+   langctl team invitations
+   ```
 
-Run `langctl init` to configure Supabase connection.
+### Security
 
-### "Project not found" error
+1. **Never commit API keys** to version control
+2. **Use environment variables**:
+   ```bash
+   export LANGCTL_API_KEY="lc_..."
+   langctl auth $LANGCTL_API_KEY
+   ```
 
-- Verify the project ID with `langctl projects list`
-- Check that your API key has access to the organization
+3. **Rotate keys periodically** from [app.langctl.com](https://app.langctl.com)
 
-### Invalid API key format
+4. **Use different keys** for different environments:
+   - Development key for local work
+   - CI/CD key for automated workflows
+   - Production key for releases
 
-API keys should:
-- Start with `lc_`
-- Be 67 characters long
-- Be generated from the Langctl dashboard
+---
 
-## Development
+## Troubleshooting
+
+### Authentication Issues
 
+**"Not authenticated" error:**
 ```bash
-# Install dependencies
-npm install
+# Solution: Authenticate with your API key
+langctl auth lc_your_api_key_here
+```
 
-# Build TypeScript
-npm run build
+**"Invalid API key" error:**
+- Verify key format (starts with `lc_`, 67 characters total)
+- Check key hasn't been revoked at [app.langctl.com](https://app.langctl.com)
+- Generate a new key if needed
 
-# Run in development mode
-npm run dev
+### Project Issues
+
+**"Project not found" error:**
+```bash
+# Check project slug (not name)
+langctl projects list
 
-# Test CLI
-node dist/index.js --help
+# Use the slug shown in the list
+langctl keys list correct-slug-here
 ```
 
-## Support
+**Cannot remove language:**
+- Cannot remove the default language
+- Change default language first:
+  ```bash
+  langctl projects update my-app --default-language en
+  langctl projects remove-language my-app fr
+  ```
+
+### Import/Export Issues
+
+**Import fails with format error:**
+- Ensure JSON is valid
+- Use flat key-value format or nested objects
+- Check language code is valid
+
+**Export shows no keys:**
+- Verify keys are published:
+  ```bash
+  langctl keys list my-app --published
+  ```
+- Or include unpublished:
+  ```bash
+  langctl export my-app -l en --include-unpublished
+  ```
+
+### Connection Issues
+
+If experiencing connectivity problems:
+1. Check your internet connection
+2. Verify you're not behind a restrictive firewall
+3. Try again in a few moments
+4. Contact support if issue persists
 
+---
+
+## FAQ
+
+**Q: What's the difference between slug and name?**
+A: The slug is the URL-friendly identifier (e.g., `my-app`), while the name is the display name (e.g., "My App"). Use slugs in CLI commands.
+
+**Q: Can I use the CLI without installing it?**
+A: Yes! Use `npx langctl` instead of `langctl` for any command.
+
+**Q: How do I get my project slug?**
+A: Run `langctl projects list` to see all project slugs.
+
+**Q: Can I export multiple languages at once?**
+A: Yes, run `langctl export my-app` without `-l` flag to export all languages.
+
+**Q: What happens to unpublished keys?**
+A: They're excluded from exports by default. Use `--include-unpublished` to include them.
+
+**Q: Can I undo a delete operation?**
+A: Projects and keys use soft deletes. Contact support to recover deleted items.
+
+**Q: How do I change my default language?**
+A: Run: `langctl projects update my-app --default-language <new-language>`
+
+**Q: Can I use the CLI in CI/CD?**
+A: Yes! Store your API key as a secret and use it in your workflow. See [CI/CD Integration](#cicd-integration).
+
+---
+
+## Platform Support
+
+- ✅ macOS (Apple Silicon & Intel)
+- ✅ Linux (x64, ARM64)
+- ✅ Windows (x64, ARM64)
+- ✅ Node.js 16.0.0 or higher
+
+---
+
+## Links
+
+- **Website:** [langctl.com](https://langctl.com)
+- **Dashboard:** [app.langctl.com](https://app.langctl.com)
 - **Documentation:** [langctl.com/docs](https://langctl.com/docs)
-- **Issues:** [github.com/siddharthsaxena0/langctl/issues](https://github.com/siddharthsaxena0/langctl/issues)
-- **Email:** hello@langctl.com
+- **GitHub:** [github.com/siddharthsaxena0/langctl](https://github.com/siddharthsaxena0/langctl)
+- **Report Issues:** [github.com/siddharthsaxena0/langctl/issues](https://github.com/siddharthsaxena0/langctl/issues)
+- **Email Support:** [hello@langctl.com](mailto:hello@langctl.com)
+
+---
+
+## Contributing
+
+We welcome contributions! Please see our [contributing guidelines](CONTRIBUTING.md) for details.
+
+---
 
 ## License
 
-MIT © Siddharth Saxena
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+**Built with ❤️ by the Langctl team**
+
+*Making translation management simple, fast, and developer-friendly.*