{"record":{"id":"381af2ce1fce3fd8","repo":"JuliusBrussee/caveman","slug":"usage-invokedcommand-audit-import-format","errorCode":null,"errorMessage":"usage: ${invokedCommand(\"audit\")} import --format <fmt> <file>","messagePattern":"usage: (.+?) import --format <fmt> <file>","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/index.ts","lineNumber":17120,"sourceCode":"  const body = await post(`/api/v1/projects/${await projectId()}/keys`, { name: flagFrom(argv, \"--name\", \"cli-key\"), scopes: [\"proxy:write\", \"sdk:write\"] });\n  print(body);\n}\n\nasync function audit(argv: string[]) {\n  if (argv[0] === \"import\") return auditImport(argv);\n  if (argv[0] === \"eval-import\") return auditEvalImport(argv);\n  if (argv[0] === \"report\") return get(`/api/v1/audits/${argv[1] ?? \"aud_demo\"}`).then(print);\n  return post(\"/api/v1/audits\", { last: flagFrom(argv, \"--last\", \"7d\") }).then(print);\n}\n\n// auditImport reads a telemetry export file and POSTs it to /api/v1/imports.\n// Usage: caveman audit import --format <fmt> <file> [--field-map <json>]\n// The org/project scope is resolved server-side from the auth token — never\n// from the file (tenant-scoped rule).\nasync function auditImport(argv: string[]) {\n  const format = flagFrom(argv, \"--format\", \"caveman-jsonl\");\n  const file = positionalAfterOptions(argv.slice(1), new Set([\"--format\", \"--field-map\"]));\n  if (!file) throw new Error(`usage: ${invokedCommand(\"audit\")} import --format <fmt> <file>`);\n  const data = await readFile(file);\n  const cfg = await config();\n  const headers: Record<string, string> = {\n    authorization: `Bearer ${cfg.token}`,\n    \"content-type\": \"application/octet-stream\",\n    \"x-cave-csrf\": \"cli\"\n  };\n  const fieldMap = flagFrom(argv, \"--field-map\", \"\");\n  if (fieldMap) headers[\"x-cave-field-map\"] = fieldMap;\n  const response = await fetch(`${cfg.baseURL}/api/v1/imports?format=${encodeURIComponent(format)}`, {\n    method: \"POST\",\n    headers,\n    body: data\n  });\n  print(await response.json());\n}\n\n// auditEvalImport turns newline-delimited, source-neutral eval records into one","sourceCodeStart":17102,"sourceCodeEnd":17138,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/5184b3d11ac6a1acb7d44b9bfaa31698157cff97/packages/cli/src/index.ts#L17102-L17138","documentation":"Usage guard for `caveman audit import`: after skipping the known options (`--format`, `--field-map`), the CLI requires exactly one positional file path pointing at a telemetry export. If no positional argument remains, this usage error is thrown before any file is read or any request is sent. Org/project scope is resolved server-side from the token, so only the file argument is needed.","triggerScenarios":"`caveman audit import --format caveman-jsonl` with the file path forgotten; the path expanded from an unset/empty shell variable; the path accidentally consumed because it was passed in an option's value position.","commonSituations":"Long flag-heavy CI commands; copy-paste from docs that used a placeholder like <file>; quoting bugs where $FILE is unset under `set -u`-less scripts.","solutions":["Append the export file path: `caveman audit import --format caveman-jsonl ./export.jsonl`","Verify the file variable is non-empty before invoking the CLI","Check the usage line in the error for the expected argument order"],"exampleFix":"# before\ncaveman audit import --format caveman-jsonl \"\"\n# after\ncaveman audit import --format caveman-jsonl \"$EXPORT_FILE\"","handlingStrategy":"validation","validationCode":"import { access } from 'node:fs/promises';\nif (!file || typeof file !== 'string') throw new Error('export file path is required');\nawait access(file); // surfaces missing files before the CLI runs","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use `set -u` in shell scripts so unset variables fail before the CLI sees them","Add `[ -f \"$EXPORT_FILE\" ]` as a CI pre-step","Keep the file path as the final argument consistently"],"tags":["cli","usage-error","audit","import"],"backgroundTag":"missing-cli-argument","analyzedSha":"5184b3d11ac6a1acb7d44b9bfaa31698157cff97","analyzedAt":"2026-08-18T03:14:35.516Z","contentChangedAt":"2026-08-18T03:14:35.516Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}