@cognivia/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manik Maurya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# @cognivia/cli
+
+Run Cognivia's learning diagnostics from a terminal or a data pipeline. Point it
+at any learning or quiz app's answer export and get back the Learning Genome and
+a session report.
+
+```bash
+npm i -g @cognivia/cli
+cognivia diagnose --demo                 # bundled sample data, no key
+cognivia diagnose --input answers.json   # your export
+cognivia memory-state <learnerId>        # hosted API (needs COGNIVIA_API_KEY)
+```
+
+With `COGNIVIA_API_KEY` set it calls the hosted API; otherwise it computes locally.
+
+MIT · Manik Maurya

package/bin/cognivia.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// @cognivia/cli - run Cognivia's diagnostics from a terminal or a data pipeline.
+//
+//   cognivia diagnose --demo                 run on bundled sample data (no key)
+//   cognivia diagnose --input answers.json   diagnose your own attempts
+//   cognivia report   --input answers.json --out report.txt
+//   cognivia memory-state --input answers.json
+//
+// answers.json is a JSON array of attempts:
+//   [{ "subject":"Physics", "question":"...", "answer":"...",
+//      "correct":true, "latencyMs":4200, "confidence":5 }]
+//
+// The diagnosis comes from @cognivia/core - the exact engine the site,
+// console, and MCP server use, so results match everywhere.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import * as core from "@cognivia/core";
+import * as client from "@cognivia/core/client";
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+const opt = (name) => { const i = args.indexOf(name); return i >= 0 ? (args[i + 1] || true) : undefined; };
+const has = (name) => args.includes(name);
+
+function loadAttempts() {
+  if (has("--demo")) return core.DEMO_ATTEMPTS;
+  const f = opt("--input");
+  if (!f || f === true) fail("provide --input <file.json> or --demo");
+  let data;
+  try { data = JSON.parse(readFileSync(f, "utf8")); }
+  catch (e) { fail("could not read/parse " + f + ": " + e.message); }
+  const arr = Array.isArray(data) ? data : data.attempts;
+  if (!Array.isArray(arr) || !arr.length) fail("input must be a non-empty JSON array of attempts");
+  return arr;
+}
+
+function fail(msg) { console.error("cognivia: " + msg); process.exit(1); }
+
+function out(text) {
+  const o = opt("--out");
+  if (o && o !== true) { writeFileSync(o, text); console.error("→ wrote " + o); }
+  else console.log(text);
+}
+
+function help() {
+  console.log(`cognivia - learning diagnostics on the command line
+
+Usage:
+  cognivia diagnose --demo
+  cognivia diagnose --input answers.json [--json] [--out file]
+  cognivia report --input answers.json [--out report.txt]
+  cognivia memory-state --input answers.json
+  cognivia --version
+
+answers.json: JSON array of { subject, question, answer, correct, latencyMs, confidence(1-5) }
+Diagnostics are computed by @cognivia/core, the same engine behind the API, MCP server, and site.`);
+}
+
+switch (cmd) {
+  case "diagnose":
+  case "report": {
+    const attempts = loadAttempts();
+    // Use the hosted API when a key is set (unless --demo or --local); else compute locally.
+    const useRemote = !has("--demo") && (has("--remote") || (client.hasKey() && !has("--local")));
+    let rep;
+    if (useRemote) {
+      try { rep = await client.reportRemote(attempts); }
+      catch (e) { console.error("cognivia: API call failed (" + e.message + "), computing locally."); }
+    }
+    if (!rep) rep = core.buildReport(attempts, { idPrefix: has("--demo") ? "CGV-DEMO" : "CGV-CLI" });
+    out(has("--json") ? JSON.stringify(rep, null, 2) : core.renderText(rep));
+    break;
+  }
+  case "memory-state": {
+    // `cognivia memory-state <learnerId>` hits the hosted API (needs a live key).
+    const id = args[1] && !args[1].startsWith("-") ? args[1] : null;
+    if (id) {
+      if (!client.hasKey()) fail("memory-state <id> needs COGNIVIA_API_KEY (a live key).");
+      try { out(JSON.stringify(await client.memoryStateRemote(id), null, 2)); }
+      catch (e) { fail("memory-state: " + e.message); }
+      break;
+    }
+    const atts = loadAttempts();
+    const lines = atts.map((a, i) =>
+      `${i + 1}. ${(a.subject || a.topic || "item").padEnd(24)} ${core.memoryState(a).padEnd(16)} ${core.diagnosis(a)}`);
+    out(lines.join("\n"));
+    break;
+  }
+  case "--version":
+  case "-v":
+    console.log("cognivia/0.1.0 (core " + "0.1.0" + ")");
+    break;
+  case undefined:
+  case "help":
+  case "--help":
+  case "-h":
+    help();
+    break;
+  default:
+    fail("unknown command '" + cmd + "'. Try: cognivia --help");
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@cognivia/cli",
+  "version": "0.1.0",
+  "description": "Run Cognivia's learning diagnostics from the terminal. Point it at any learning or quiz app's answer export and get back the Learning Genome, per-item diagnosis, and a session report.",
+  "type": "module",
+  "bin": { "cognivia": "bin/cognivia.mjs" },
+  "files": ["bin", "README.md", "LICENSE"],
+  "keywords": ["cognivia", "learning", "diagnostics", "cli", "edtech", "spaced-repetition"],
+  "homepage": "https://cognivia-platform.vercel.app/intelligence",
+  "repository": { "type": "git", "url": "git+https://github.com/Manik-Maurya/cognivia-platform.git", "directory": "packages/cli" },
+  "engines": { "node": ">=18" },
+  "dependencies": { "@cognivia/core": "^0.1.0" },
+  "publishConfig": { "access": "public" },
+  "license": "MIT",
+  "author": "Manik Maurya"
+}