@kopynator/cli 1.3.0 → 1.4.0

package/README.md

@@ -43,6 +43,8 @@ npx -y @kopynator/cli sync
 ### 4. Upload
 Uploads a JSON translation file to the Kopynator Cloud. Keys are merged/updated for the given language. Use the same API key (token) as in your app or `kopynator.config.json`.
 
+**Project:** The target project is determined by the token. Each token is linked to one project when created in [Dashboard → Settings → Tokens](https://www.kopynator.com/dashboard/settings/tokens). To upload to a different project, use that project’s token (e.g. another `apiKey` in `kopynator.config.json` or a separate config).
+
 ```bash
 # Language inferred from filename (es.json → es)
 npx -y @kopynator/cli upload --file=src/assets/i18n/es.json

package/dist/index.js

@@ -341,10 +341,32 @@ function getTranslationDir(framework) {
       return import_path3.default.join(process.cwd(), "locales");
   }
 }
+function loadJsonConfig(jsonPath) {
+  if (!import_fs3.default.existsSync(jsonPath)) return null;
+  try {
+    const config = JSON.parse(import_fs3.default.readFileSync(jsonPath, "utf-8"));
+    if (config.apiKey) return { apiKey: config.apiKey, baseUrl: config.baseUrl };
+  } catch (e) {
+    if (jsonPath.includes("kopynator.config.json")) {
+      console.log(import_chalk3.default.red("\u274C Error parsing kopynator.config.json"));
+    }
+  }
+  return null;
+}
 function extractApiKey() {
-  const appConfigPath = import_path3.default.join(process.cwd(), "src/app/app.config.ts");
-  const appModulePath = import_path3.default.join(process.cwd(), "src/app/app.module.ts");
-  const jsonConfigPath = import_path3.default.join(process.cwd(), "kopynator.config.json");
+  const cwd = process.cwd();
+  const configFromRoot = loadJsonConfig(import_path3.default.join(cwd, "kopynator.config.json"));
+  if (configFromRoot) {
+    console.log(import_chalk3.default.blue("\u2139\uFE0F  Found API key in kopynator.config.json"));
+    return configFromRoot;
+  }
+  const configFromSrc = loadJsonConfig(import_path3.default.join(cwd, "src/kopynator.config.json"));
+  if (configFromSrc) {
+    console.log(import_chalk3.default.blue("\u2139\uFE0F  Found API key in src/kopynator.config.json"));
+    return configFromSrc;
+  }
+  const appConfigPath = import_path3.default.join(cwd, "src/app/app.config.ts");
+  const appModulePath = import_path3.default.join(cwd, "src/app/app.module.ts");
   if (import_fs3.default.existsSync(appConfigPath)) {
     const content = import_fs3.default.readFileSync(appConfigPath, "utf-8");
     const apiKeyMatch = content.match(/apiKey:\s*['"]([^'"]+)['"]/);
@@ -361,16 +383,13 @@ function extractApiKey() {
       return { apiKey: apiKeyMatch[1] };
     }
   }
-  if (import_fs3.default.existsSync(jsonConfigPath)) {
-    try {
-      const config = JSON.parse(import_fs3.default.readFileSync(jsonConfigPath, "utf-8"));
-      if (config.apiKey) {
-        console.log(import_chalk3.default.blue("\u2139\uFE0F  Found API key in kopynator.config.json"));
-        return { apiKey: config.apiKey, baseUrl: config.baseUrl };
-      }
-    } catch (e) {
-      console.log(import_chalk3.default.red("\u274C Error parsing kopynator.config.json"));
-    }
+  const envKey = process.env.KOPYNATOR_API_KEY?.trim();
+  if (envKey) {
+    console.log(import_chalk3.default.blue("\u2139\uFE0F  Using API key from KOPYNATOR_API_KEY"));
+    return {
+      apiKey: envKey,
+      baseUrl: process.env.KOPYNATOR_BASE_URL?.trim() || void 0
+    };
   }
   return null;
 }
@@ -446,7 +465,7 @@ async function syncCommand() {
     const languagesUrl = `${baseUrl}/languages?token=${token}`;
     const languagesResponse = await fetch(languagesUrl, {
       headers: {
-        "x-kopynator-version": "1.1.0"
+        "x-kopynator-version": "1.4.0"
       }
     });
     if (!languagesResponse.ok) {
@@ -466,7 +485,7 @@ async function syncCommand() {
       try {
         const translationResponse = await fetch(fetchUrl, {
           headers: {
-            "x-kopynator-version": "1.1.0"
+            "x-kopynator-version": "1.4.0"
           }
         });
         if (!translationResponse.ok) {
@@ -513,10 +532,24 @@ function flatten(data, prefix = "") {
   }
   return result;
 }
+function loadJsonConfig2(jsonPath) {
+  if (!import_fs4.default.existsSync(jsonPath)) return null;
+  try {
+    const config = JSON.parse(import_fs4.default.readFileSync(jsonPath, "utf-8"));
+    const key = config.apiKey ?? config.api_key;
+    if (key && typeof key === "string") return { apiKey: key, baseUrl: config.baseUrl };
+  } catch {
+  }
+  return null;
+}
 function extractApiKey2() {
-  const appConfigPath = import_path4.default.join(process.cwd(), "src/app/app.config.ts");
-  const appModulePath = import_path4.default.join(process.cwd(), "src/app/app.module.ts");
-  const jsonConfigPath = import_path4.default.join(process.cwd(), "kopynator.config.json");
+  const cwd = process.cwd();
+  const appConfigPath = import_path4.default.join(cwd, "src/app/app.config.ts");
+  const appModulePath = import_path4.default.join(cwd, "src/app/app.module.ts");
+  const configFromRoot = loadJsonConfig2(import_path4.default.join(cwd, "kopynator.config.json"));
+  if (configFromRoot) return configFromRoot;
+  const configFromSrc = loadJsonConfig2(import_path4.default.join(cwd, "src/kopynator.config.json"));
+  if (configFromSrc) return configFromSrc;
   if (import_fs4.default.existsSync(appConfigPath)) {
     const content = import_fs4.default.readFileSync(appConfigPath, "utf-8");
     const apiKeyMatch = content.match(/apiKey:\s*['"]([^'"]+)['"]/);
@@ -527,12 +560,12 @@ function extractApiKey2() {
     const apiKeyMatch = content.match(/apiKey:\s*['"]([^'"]+)['"]/);
     if (apiKeyMatch) return { apiKey: apiKeyMatch[1] };
   }
-  if (import_fs4.default.existsSync(jsonConfigPath)) {
-    try {
-      const config = JSON.parse(import_fs4.default.readFileSync(jsonConfigPath, "utf-8"));
-      if (config.apiKey) return { apiKey: config.apiKey, baseUrl: config.baseUrl };
-    } catch {
-    }
+  const envKey = process.env.KOPYNATOR_API_KEY?.trim();
+  if (envKey) {
+    return {
+      apiKey: envKey,
+      baseUrl: process.env.KOPYNATOR_BASE_URL?.trim() || void 0
+    };
   }
   return null;
 }
@@ -544,7 +577,18 @@ async function uploadCommand(options) {
   console.log(import_chalk4.default.bold.blue("\n\u{1F4E4} Upload translations to Kopynator Cloud...\n"));
   const config = extractApiKey2();
   if (!config) {
-    console.log(import_chalk4.default.red("\u274C Could not find API key. Run `npx kopynator init` or set apiKey in kopynator.config.json / app.config.ts"));
+    const cwd = process.cwd();
+    const rootConfig = import_path4.default.join(cwd, "kopynator.config.json");
+    const srcConfig = import_path4.default.join(cwd, "src/kopynator.config.json");
+    console.log(import_chalk4.default.red("\u274C Could not find API key. Set it in kopynator.config.json, app.config.ts, or KOPYNATOR_API_KEY. Run `npx kopynator init` to create config."));
+    console.log(import_chalk4.default.gray(`   Directorio actual: ${cwd}`));
+    console.log(import_chalk4.default.gray(`   Comprobado: ${rootConfig} (${import_fs4.default.existsSync(rootConfig) ? "existe" : "no existe"})`));
+    console.log(import_chalk4.default.gray(`   Comprobado: ${srcConfig} (${import_fs4.default.existsSync(srcConfig) ? "existe" : "no existe"})`));
+    if (import_fs4.default.existsSync(rootConfig) || import_fs4.default.existsSync(srcConfig)) {
+      console.log(import_chalk4.default.yellow('\u{1F4A1} Si el archivo existe, comprueba que tenga la propiedad "apiKey" (o "api_key") con un valor no vac\xEDo.'));
+    } else {
+      console.log(import_chalk4.default.yellow("\u{1F4A1} Ejecuta el comando desde la ra\xEDz del proyecto (donde est\xE1 package.json)."));
+    }
     return;
   }
   const fileOption = options.file;
@@ -558,7 +602,7 @@ async function uploadCommand(options) {
     return;
   }
   const lang = options.lang || inferLangFromFile(resolvedPath);
-  const baseUrl = config.baseUrl || "https://api.kopynator.com/api/tokens";
+  const baseUrl = config.baseUrl || "https://api.kopynator.com/tokens";
   const token = config.apiKey;
   let raw;
   try {
@@ -583,41 +627,79 @@ async function uploadCommand(options) {
     batches.push(Object.fromEntries(entries.slice(i, i + BATCH_SIZE)));
   }
   const spinner = (0, import_ora2.default)(`Uploading ${total} keys (${lang})...`).start();
-  try {
+  const DEFAULT_API_BASE = "https://api.kopynator.com/tokens";
+  const FALLBACK_API_BASE = "https://api.kopynator.com/api/tokens";
+  const doUpload = async (urlBase) => {
     let imported = 0;
     for (let i = 0; i < batches.length; i++) {
       spinner.text = `Uploading batch ${i + 1}/${batches.length}...`;
-      const res = await fetch(`${baseUrl}/import`, {
+      const res = await fetch(`${urlBase}/import`, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
           "x-api-token": token,
-          "x-kopynator-version": "1.2.0"
+          "x-kopynator-version": "1.4.0"
         },
         body: JSON.stringify({ lang, data: batches[i] })
       });
       if (!res.ok) {
         const errText = await res.text();
-        spinner.fail(`Upload failed: ${res.status} ${errText}`);
-        return;
+        let errMsg;
+        try {
+          const errJson = JSON.parse(errText);
+          errMsg = errJson.message || errJson.error || errText;
+        } catch {
+          errMsg = errText || res.statusText;
+        }
+        return { ok: false, status: res.status, errMsg };
       }
       const result = await res.json();
-      imported += result.importedCount ?? batches[i].length;
+      imported += Number(result.importedCount ?? Object.keys(batches[i]).length);
     }
-    spinner.succeed(import_chalk4.default.green(`Uploaded ${imported} keys for language "${lang}".`));
-    console.log(import_chalk4.default.bold.green("\n\u{1F389} Upload completed. Run `npx kopynator sync` to pull latest from cloud.\n"));
+    return { ok: true, imported };
+  };
+  try {
+    let result = await doUpload(baseUrl);
+    let triedFallback = false;
+    if (!result.ok && result.status === 404 && baseUrl === DEFAULT_API_BASE) {
+      spinner.text = "Reintentando con URL alternativa...";
+      result = await doUpload(FALLBACK_API_BASE);
+      triedFallback = true;
+    }
+    if (result.ok) {
+      spinner.succeed(import_chalk4.default.green(`Uploaded ${result.imported} keys for language "${lang}".`));
+      console.log(import_chalk4.default.bold.green("\n\u{1F389} Upload completed. Run `npx kopynator sync` to pull latest from cloud.\n"));
+      return;
+    }
+    spinner.fail(`Upload failed: ${result.status} ${result.errMsg}`);
+    if (result.status === 401) {
+      console.log(import_chalk4.default.yellow("\u{1F4A1} Comprueba que el API key sea correcto (Dashboard \u2192 Settings \u2192 Tokens)."));
+    }
+    if (result.status === 404) {
+      console.log(import_chalk4.default.yellow("\u{1F4A1} Comprueba que la API est\xE9 desplegada y que la URL sea correcta (KOPYNATOR_BASE_URL si usas entorno propio)."));
+    }
+    console.log(import_chalk4.default.gray(`   URL usada: ${baseUrl}/import`));
+    if (triedFallback) console.log(import_chalk4.default.gray(`   (tambi\xE9n probada: ${FALLBACK_API_BASE}/import)`));
   } catch (error) {
-    spinner.fail(`Upload failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+    const msg = error instanceof Error ? error.message : String(error);
+    spinner.fail(`Upload failed: ${msg}`);
+    if (msg.includes("fetch") || msg.includes("ECONNREFUSED") || msg.includes("ENOTFOUND")) {
+      console.log(import_chalk4.default.yellow("\u{1F4A1} Comprueba conexi\xF3n y que la API est\xE9 disponible. Para entorno local: KOPYNATOR_BASE_URL=http://localhost:7300/api/tokens"));
+    }
   }
 }
 
 // src/index.ts
 var program = new import_commander.Command();
-program.name("kopynator").description("Kopynator CLI - Manage your i18n workflow").version("1.3.0");
+program.name("kopynator").description("Kopynator CLI - Manage your i18n workflow").version("1.4.0");
 program.command("init").description("Initialize Kopynator in your project").action(initCommand);
 program.command("check").description("Validate your local JSON translation files").action(checkCommand);
 program.command("sync").description("Sync your translations with the Kopynator Cloud").action(syncCommand);
 program.command("upload").description("Upload a JSON translation file to Kopynator Cloud").option("-f, --file <path>", "Path to the JSON file (e.g. es.json)").option("-l, --lang <code>", "Language code (default: inferred from filename)").action((opts) => uploadCommand({ file: opts.file, lang: opts.lang }));
+program.command("help").description("Show help for all commands").action(() => {
+  console.log(import_chalk5.default.blue("\u{1F44B} Kopynator CLI - Comandos disponibles:\n"));
+  program.outputHelp();
+});
 program.parse(process.argv);
 if (!process.argv.slice(2).length) {
   console.log(import_chalk5.default.blue("\u{1F44B} Welcome to Kopynator CLI!"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kopynator/cli",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "CLI tool for Kopynator - The i18n management solution",
   "bin": {
     "kopynator": "dist/index.js"

package/src/commands/sync.ts

@@ -65,15 +65,40 @@ function getTranslationDir(framework: string): string {
 }
 
 /**
- * Extract API key from Angular config files or JSON config
- * Tries: app.config.ts -> app.module.ts -> kopynator.config.json
+ * API key del proyecto primero (no hace falta en el comando), luego env para CI.
+ * Order: app.config.ts -> app.module.ts -> kopynator.config.json -> KOPYNATOR_API_KEY
  */
+function loadJsonConfig(jsonPath: string): KopyConfig | null {
+  if (!fs.existsSync(jsonPath)) return null;
+  try {
+    const config = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
+    if (config.apiKey) return { apiKey: config.apiKey, baseUrl: config.baseUrl };
+  } catch (e) {
+    if (jsonPath.includes('kopynator.config.json')) {
+      console.log(chalk.red('❌ Error parsing kopynator.config.json'));
+    }
+  }
+  return null;
+}
+
 function extractApiKey(): KopyConfig | null {
-  const appConfigPath = path.join(process.cwd(), 'src/app/app.config.ts');
-  const appModulePath = path.join(process.cwd(), 'src/app/app.module.ts');
-  const jsonConfigPath = path.join(process.cwd(), 'kopynator.config.json');
+  const cwd = process.cwd();
 
-  // Try app.config.ts
+  // 1) kopynator.config.json (raíz o src/) — funciona aunque en app.config uses apiKey: kopynatorConfig.apiKey
+  const configFromRoot = loadJsonConfig(path.join(cwd, 'kopynator.config.json'));
+  if (configFromRoot) {
+    console.log(chalk.blue('ℹ️  Found API key in kopynator.config.json'));
+    return configFromRoot;
+  }
+  const configFromSrc = loadJsonConfig(path.join(cwd, 'src/kopynator.config.json'));
+  if (configFromSrc) {
+    console.log(chalk.blue('ℹ️  Found API key in src/kopynator.config.json'));
+    return configFromSrc;
+  }
+
+  // 2) Literales en app.config.ts / app.module.ts
+  const appConfigPath = path.join(cwd, 'src/app/app.config.ts');
+  const appModulePath = path.join(cwd, 'src/app/app.module.ts');
   if (fs.existsSync(appConfigPath)) {
     const content = fs.readFileSync(appConfigPath, 'utf-8');
     const apiKeyMatch = content.match(/apiKey:\s*['"]([^'"]+)['"]/);
@@ -82,8 +107,6 @@ function extractApiKey(): KopyConfig | null {
       return { apiKey: apiKeyMatch[1] };
     }
   }
-
-  // Try app.module.ts
   if (fs.existsSync(appModulePath)) {
     const content = fs.readFileSync(appModulePath, 'utf-8');
     const apiKeyMatch = content.match(/apiKey:\s*['"]([^'"]+)['"]/);
@@ -93,19 +116,15 @@ function extractApiKey(): KopyConfig | null {
     }
   }
 
-  // Try kopynator.config.json
-  if (fs.existsSync(jsonConfigPath)) {
-    try {
-      const config = JSON.parse(fs.readFileSync(jsonConfigPath, 'utf-8'));
-      if (config.apiKey) {
-        console.log(chalk.blue('ℹ️  Found API key in kopynator.config.json'));
-        return { apiKey: config.apiKey, baseUrl: config.baseUrl };
-      }
-    } catch (e) {
-      console.log(chalk.red('❌ Error parsing kopynator.config.json'));
-    }
+  // Env (CI)
+  const envKey = process.env.KOPYNATOR_API_KEY?.trim();
+  if (envKey) {
+    console.log(chalk.blue('ℹ️  Using API key from KOPYNATOR_API_KEY'));
+    return {
+      apiKey: envKey,
+      baseUrl: process.env.KOPYNATOR_BASE_URL?.trim() || undefined,
+    };
   }
-
   return null;
 }
 
@@ -204,7 +223,7 @@ export async function syncCommand() {
     const languagesUrl = `${baseUrl}/languages?token=${token}`;
     const languagesResponse = await fetch(languagesUrl, {
       headers: {
-        'x-kopynator-version': '1.1.0'
+        'x-kopynator-version': '1.4.0'
       }
     });
     if (!languagesResponse.ok) {
@@ -230,7 +249,7 @@ export async function syncCommand() {
       try {
         const translationResponse = await fetch(fetchUrl, {
           headers: {
-            'x-kopynator-version': '1.1.0'
+            'x-kopynator-version': '1.4.0'
           }
         });
 

package/src/commands/upload.ts

@@ -27,11 +27,35 @@ function flatten(data: Record<string, unknown>, prefix = ''): Record<string, str
   return result;
 }
 
+/**
+ * Obtiene el API key y baseUrl del proyecto para enviarlos en la petición.
+ * Prioridad: archivos del proyecto (no hace falta poner el key en el comando) → env para CI.
+ * El backend identifica el proyecto por el token en el header x-api-token.
+ */
+function loadJsonConfig(jsonPath: string): KopyConfig | null {
+  if (!fs.existsSync(jsonPath)) return null;
+  try {
+    const config = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
+    const key = config.apiKey ?? config.api_key;
+    if (key && typeof key === 'string') return { apiKey: key, baseUrl: config.baseUrl };
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
 function extractApiKey(): KopyConfig | null {
-  const appConfigPath = path.join(process.cwd(), 'src/app/app.config.ts');
-  const appModulePath = path.join(process.cwd(), 'src/app/app.module.ts');
-  const jsonConfigPath = path.join(process.cwd(), 'kopynator.config.json');
+  const cwd = process.cwd();
+  const appConfigPath = path.join(cwd, 'src/app/app.config.ts');
+  const appModulePath = path.join(cwd, 'src/app/app.module.ts');
+
+  // 1) kopynator.config.json (raíz o src/) — así funciona aunque en app.config uses apiKey: kopynatorConfig.apiKey
+  const configFromRoot = loadJsonConfig(path.join(cwd, 'kopynator.config.json'));
+  if (configFromRoot) return configFromRoot;
+  const configFromSrc = loadJsonConfig(path.join(cwd, 'src/kopynator.config.json'));
+  if (configFromSrc) return configFromSrc;
 
+  // 2) Literales en app.config.ts / app.module.ts
   if (fs.existsSync(appConfigPath)) {
     const content = fs.readFileSync(appConfigPath, 'utf-8');
     const apiKeyMatch = content.match(/apiKey:\s*['"]([^'"]+)['"]/);
@@ -42,13 +66,14 @@ function extractApiKey(): KopyConfig | null {
     const apiKeyMatch = content.match(/apiKey:\s*['"]([^'"]+)['"]/);
     if (apiKeyMatch) return { apiKey: apiKeyMatch[1] };
   }
-  if (fs.existsSync(jsonConfigPath)) {
-    try {
-      const config = JSON.parse(fs.readFileSync(jsonConfigPath, 'utf-8'));
-      if (config.apiKey) return { apiKey: config.apiKey, baseUrl: config.baseUrl };
-    } catch {
-      // ignore
-    }
+
+  // 2) Env (útil en CI donde no hay app.config/kopynator.config.json)
+  const envKey = process.env.KOPYNATOR_API_KEY?.trim();
+  if (envKey) {
+    return {
+      apiKey: envKey,
+      baseUrl: process.env.KOPYNATOR_BASE_URL?.trim() || undefined,
+    };
   }
   return null;
 }
@@ -66,7 +91,18 @@ export async function uploadCommand(options: { file?: string; lang?: string }) {
 
   const config = extractApiKey();
   if (!config) {
-    console.log(chalk.red('❌ Could not find API key. Run `npx kopynator init` or set apiKey in kopynator.config.json / app.config.ts'));
+    const cwd = process.cwd();
+    const rootConfig = path.join(cwd, 'kopynator.config.json');
+    const srcConfig = path.join(cwd, 'src/kopynator.config.json');
+    console.log(chalk.red('❌ Could not find API key. Set it in kopynator.config.json, app.config.ts, or KOPYNATOR_API_KEY. Run `npx kopynator init` to create config.'));
+    console.log(chalk.gray(`   Directorio actual: ${cwd}`));
+    console.log(chalk.gray(`   Comprobado: ${rootConfig} (${fs.existsSync(rootConfig) ? 'existe' : 'no existe'})`));
+    console.log(chalk.gray(`   Comprobado: ${srcConfig} (${fs.existsSync(srcConfig) ? 'existe' : 'no existe'})`));
+    if (fs.existsSync(rootConfig) || fs.existsSync(srcConfig)) {
+      console.log(chalk.yellow('💡 Si el archivo existe, comprueba que tenga la propiedad "apiKey" (o "api_key") con un valor no vacío.'));
+    } else {
+      console.log(chalk.yellow('💡 Ejecuta el comando desde la raíz del proyecto (donde está package.json).'));
+    }
     return;
   }
 
@@ -83,7 +119,9 @@ export async function uploadCommand(options: { file?: string; lang?: string }) {
   }
 
   const lang = options.lang || inferLangFromFile(resolvedPath);
-  const baseUrl = config.baseUrl || 'https://api.kopynator.com/api/tokens';
+  // Backend expone /tokens/import sin prefijo /api (exclude en setGlobalPrefix)
+  const baseUrl = config.baseUrl || 'https://api.kopynator.com/tokens';
+  // Token enviado en la petición: el backend lo usa para saber a qué proyecto importar (como en la web)
   const token = config.apiKey;
 
   let raw: unknown;
@@ -114,32 +152,69 @@ export async function uploadCommand(options: { file?: string; lang?: string }) {
 
   const spinner = ora(`Uploading ${total} keys (${lang})...`).start();
 
-  try {
+  const DEFAULT_API_BASE = 'https://api.kopynator.com/tokens';
+  const FALLBACK_API_BASE = 'https://api.kopynator.com/api/tokens';
+
+  const doUpload = async (urlBase: string): Promise<{ ok: true; imported: number } | { ok: false; status: number; errMsg: string }> => {
     let imported = 0;
     for (let i = 0; i < batches.length; i++) {
       spinner.text = `Uploading batch ${i + 1}/${batches.length}...`;
-      const res = await fetch(`${baseUrl}/import`, {
+      const res = await fetch(`${urlBase}/import`, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
           'x-api-token': token,
-          'x-kopynator-version': '1.2.0',
+          'x-kopynator-version': '1.4.0',
         },
         body: JSON.stringify({ lang, data: batches[i] }),
       });
-
       if (!res.ok) {
         const errText = await res.text();
-        spinner.fail(`Upload failed: ${res.status} ${errText}`);
-        return;
+        let errMsg: string;
+        try {
+          const errJson = JSON.parse(errText) as { message?: string; error?: string };
+          errMsg = errJson.message || errJson.error || errText;
+        } catch {
+          errMsg = errText || res.statusText;
+        }
+        return { ok: false, status: res.status, errMsg };
       }
       const result = (await res.json()) as { importedCount?: number };
-      imported += result.importedCount ?? batches[i].length;
+      imported += Number(result.importedCount ?? Object.keys(batches[i]).length);
+    }
+    return { ok: true, imported };
+  };
+
+  try {
+    let result = await doUpload(baseUrl);
+    let triedFallback = false;
+
+    if (!result.ok && result.status === 404 && baseUrl === DEFAULT_API_BASE) {
+      spinner.text = 'Reintentando con URL alternativa...';
+      result = await doUpload(FALLBACK_API_BASE);
+      triedFallback = true;
+    }
+
+    if (result.ok) {
+      spinner.succeed(chalk.green(`Uploaded ${result.imported} keys for language "${lang}".`));
+      console.log(chalk.bold.green('\n🎉 Upload completed. Run `npx kopynator sync` to pull latest from cloud.\n'));
+      return;
     }
 
-    spinner.succeed(chalk.green(`Uploaded ${imported} keys for language "${lang}".`));
-    console.log(chalk.bold.green('\n🎉 Upload completed. Run `npx kopynator sync` to pull latest from cloud.\n'));
+    spinner.fail(`Upload failed: ${result.status} ${result.errMsg}`);
+    if (result.status === 401) {
+      console.log(chalk.yellow('💡 Comprueba que el API key sea correcto (Dashboard → Settings → Tokens).'));
+    }
+    if (result.status === 404) {
+      console.log(chalk.yellow('💡 Comprueba que la API esté desplegada y que la URL sea correcta (KOPYNATOR_BASE_URL si usas entorno propio).'));
+    }
+    console.log(chalk.gray(`   URL usada: ${baseUrl}/import`));
+    if (triedFallback) console.log(chalk.gray(`   (también probada: ${FALLBACK_API_BASE}/import)`));
   } catch (error) {
-    spinner.fail(`Upload failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    const msg = error instanceof Error ? error.message : String(error);
+    spinner.fail(`Upload failed: ${msg}`);
+    if (msg.includes('fetch') || msg.includes('ECONNREFUSED') || msg.includes('ENOTFOUND')) {
+      console.log(chalk.yellow('💡 Comprueba conexión y que la API esté disponible. Para entorno local: KOPYNATOR_BASE_URL=http://localhost:7300/api/tokens'));
+    }
   }
 }

package/src/index.ts

@@ -8,7 +8,7 @@ const program = new Command();
 program
   .name('kopynator')
   .description('Kopynator CLI - Manage your i18n workflow')
-  .version('1.3.0');
+  .version('1.4.0');
 
 program
   .command('init')
@@ -32,6 +32,14 @@ program
   .option('-l, --lang <code>', 'Language code (default: inferred from filename)')
   .action((opts) => uploadCommand({ file: opts.file, lang: opts.lang }));
 
+program
+  .command('help')
+  .description('Show help for all commands')
+  .action(() => {
+    console.log(chalk.blue('👋 Kopynator CLI - Comandos disponibles:\n'));
+    program.outputHelp();
+  });
+
 program.parse(process.argv);
 
 if (!process.argv.slice(2).length) {