@kiipu/cli 0.0.7 → 0.0.9

package/README.md

@@ -1,14 +1,15 @@
 # Kiipu CLI
 
-Publish to Kiipu from your terminal.
+Create Kiipu notes from your terminal.
 
-`@kiipu/cli` is the official command line interface for Kiipu. It is the best place to start if you want to authenticate locally and post directly from the command line.
+`@kiipu/cli` is the official command line interface for Kiipu. It is the best place to start if you want to authenticate locally and note directly from the command line.
 
 Use it to:
 
 - sign in on the current device
-- publish posts from the command line
-- delete, restore, or permanently remove posts by id
+- ask questions over your saved notes
+- create notes from the command line
+- delete, restore, or permanently remove notes by id
 - verify local authentication and API access with `kiipu doctor`
 
 If you want Claude Code integration on top of the CLI, use `@kiipu/claude-plugin`.
@@ -27,10 +28,10 @@ npm install -g @kiipu/cli
 kiipu auth login
 ```
 
-2. Publish a post:
+2. Create a note:
 
 ```bash
-kiipu post create "Hello Kiipu"
+kiipu note create "Hello Kiipu"
 ```
 
 3. Confirm local setup:
@@ -39,11 +40,18 @@ kiipu post create "Hello Kiipu"
 kiipu doctor
 ```
 
+4. Ask over your saved notes:
+
+```bash
+kiipu ask "What did I save about the roadmap?"
+```
+
 ## Example Workflow
 
 ```bash
 kiipu auth login
-kiipu post create "Ship the beta today"
+kiipu ask "What should I follow up on?"
+kiipu note create "Ship the beta today"
 kiipu auth status
 ```
 
@@ -65,21 +73,38 @@ kiipu auth status
 kiipu auth logout
 ```
 
-## Posting
+## Noteing
+
+Create a note:
+
+```bash
+kiipu note create "Ship the beta today"
+kiipu note create --content "Ship the beta today"
+```
+
+Delete, restore, or permanently remove a note by id:
 
-Create a post:
+```bash
+kiipu note delete --id note_123
+kiipu note restore --id note_123
+kiipu note purge --id note_123
+```
+
+## Ask
+
+Ask a new question and stream the answer:
 
 ```bash
-kiipu post create "Ship the beta today"
-kiipu post create --content "Ship the beta today"
+kiipu ask "What did I save about the roadmap?"
+kiipu ask --question "What should I follow up on?"
 ```
 
-Delete, restore, or permanently remove a post by id:
+Continue a conversation or inspect Ask history:
 
 ```bash
-kiipu post delete --id post_123
-kiipu post restore --id post_123
-kiipu post purge --id post_123
+kiipu ask --conversation-id conv_123 "What should I do next?"
+kiipu ask history --limit 10
+kiipu ask show --id conv_123
 ```
 
 ## Core Commands
@@ -89,10 +114,14 @@ kiipu auth login
 kiipu auth status
 kiipu auth logout
 
-kiipu post create "Hello Kiipu"
-kiipu post delete --id post_123
-kiipu post restore --id post_123
-kiipu post purge --id post_123
+kiipu ask "What did I save about the roadmap?"
+kiipu ask history --limit 10
+kiipu ask show --id conv_123
+
+kiipu note create "Hello Kiipu"
+kiipu note delete --id note_123
+kiipu note restore --id note_123
+kiipu note purge --id note_123
 
 kiipu doctor
 kiipu --help
@@ -122,5 +151,6 @@ See the full command reference in the terminal:
 ```bash
 kiipu --help
 kiipu auth --help
-kiipu post --help
+kiipu ask --help
+kiipu note --help
 ```

package/dist/commands/ask.js

@@ -0,0 +1,229 @@
+import { KiipuAskClient } from '../lib/ask-client.js';
+import { formatAskFooter, formatConversationDetail, formatConversationHistory, } from '../lib/ask-formatters.js';
+import { hasFlag, readFlag } from '../utils/args.js';
+const sourceModes = new Set(['fresh', 'locked']);
+function error(message, data) {
+    return {
+        ok: false,
+        message,
+        ...(data ? { data, json: { ok: false, message, ...data } } : {}),
+    };
+}
+function usage(action) {
+    if (action === 'history') {
+        return 'Usage: kiipu ask history [--query <q>] [--limit <n>] [--archived]';
+    }
+    if (action === 'show') {
+        return 'Usage: kiipu ask show --id <conversationId>';
+    }
+    return [
+        'Usage: kiipu ask "question"',
+        '   or: kiipu ask --question "question"',
+        '   or: kiipu ask --conversation-id <id> "follow-up"',
+    ].join('\n');
+}
+function getAskClient(config) {
+    const apiKey = config.apiKey ?? process.env.KIIPU_API_KEY ?? '';
+    if (!apiKey) {
+        return {
+            error: error('Kiipu API key is missing. Run `kiipu auth login` first.', {
+                code: 'missing_api_key',
+            }),
+        };
+    }
+    return {
+        client: new KiipuAskClient({
+            apiBaseUrl: config.apiBaseUrl,
+            apiKey,
+        }),
+    };
+}
+function stripKnownFlags(args, flagsWithValues) {
+    const positional = [];
+    const flags = new Set(flagsWithValues);
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg) {
+            continue;
+        }
+        if (flags.has(arg)) {
+            index += 1;
+            continue;
+        }
+        if (!arg.startsWith('--')) {
+            positional.push(arg);
+        }
+    }
+    return positional;
+}
+function parseTopK(args) {
+    const raw = readFlag(args, '--top-k');
+    if (!raw) {
+        return undefined;
+    }
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1 || value > 20) {
+        return null;
+    }
+    return value;
+}
+function parseLimit(args) {
+    const raw = readFlag(args, '--limit');
+    if (!raw) {
+        return undefined;
+    }
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1 || value > 50) {
+        return null;
+    }
+    return value;
+}
+function parseSourceMode(args) {
+    const value = readFlag(args, '--source-mode');
+    if (!value) {
+        return undefined;
+    }
+    return sourceModes.has(value) ? value : null;
+}
+function readQuestion(args) {
+    const explicit = readFlag(args, '--question')?.trim();
+    if (explicit) {
+        return explicit;
+    }
+    return stripKnownFlags(args, ['--question', '--conversation-id', '--top-k', '--source-mode'])
+        .join(' ')
+        .trim();
+}
+async function handleHistory(config, args) {
+    const { client, error: clientError } = getAskClient(config);
+    if (!client) {
+        return clientError;
+    }
+    const limit = parseLimit(args);
+    if (limit === null) {
+        return error(`Invalid --limit value. ${usage('history')}`, { code: 'invalid_limit' });
+    }
+    const response = await client.listConversations({
+        query: readFlag(args, '--query'),
+        limit,
+        archived: hasFlag(args, '--archived'),
+    });
+    if (!response.ok) {
+        return error(response.error.message, response.error);
+    }
+    return {
+        ok: true,
+        message: formatConversationHistory(hasFlag(args, '--archived') ? 'Archived Ask conversations' : 'Ask conversations', response.data.items, response.data.nextCursor),
+        data: response.data,
+    };
+}
+async function handleShow(config, args) {
+    const { client, error: clientError } = getAskClient(config);
+    if (!client) {
+        return clientError;
+    }
+    const id = readFlag(args, '--id')?.trim();
+    if (!id) {
+        return error(usage('show'), { code: 'missing_conversation_id' });
+    }
+    const response = await client.getConversation(id);
+    if (!response.ok) {
+        return error(response.error.message, response.error);
+    }
+    return {
+        ok: true,
+        message: formatConversationDetail(response.data),
+        data: response.data,
+    };
+}
+async function handleQuestion(config, args, options) {
+    const { client, error: clientError } = getAskClient(config);
+    if (!client) {
+        return clientError;
+    }
+    const question = readQuestion(args);
+    if (!question) {
+        return error(usage(), { code: 'missing_question' });
+    }
+    const topK = parseTopK(args);
+    if (topK === null) {
+        return error(`Invalid --top-k value. ${usage()}`, { code: 'invalid_top_k' });
+    }
+    const sourceMode = parseSourceMode(args);
+    if (sourceMode === null) {
+        return error('Invalid --source-mode value. Use fresh or locked.', {
+            code: 'invalid_source_mode',
+        });
+    }
+    const result = {
+        answer: '',
+        conversationId: readFlag(args, '--conversation-id')?.trim() || undefined,
+        sources: [],
+    };
+    const targetConversationId = result.conversationId ?? 'new';
+    for await (const event of client.streamMessage({
+        conversationId: targetConversationId,
+        question,
+        topK,
+        sourceMode,
+    })) {
+        switch (event.type) {
+            case 'meta':
+                result.conversationId = event.conversationId;
+                result.title = event.title;
+                break;
+            case 'sources':
+                result.sources = event.sources;
+                break;
+            case 'delta':
+                result.answer += event.text;
+                if (options.stream) {
+                    options.write?.(event.text);
+                }
+                break;
+            case 'done':
+                result.turnId = event.turnId;
+                result.usage = {
+                    inputTokens: event.inputTokens,
+                    outputTokens: event.outputTokens,
+                    latencyMs: event.latencyMs,
+                };
+                break;
+            case 'title':
+                result.conversationId = event.conversationId;
+                result.title = event.title;
+                break;
+            case 'error':
+                return error(event.message, {
+                    code: event.code,
+                    answer: result.answer,
+                    conversationId: result.conversationId,
+                    title: result.title,
+                    turnId: result.turnId,
+                    sources: result.sources,
+                    usage: result.usage,
+                });
+        }
+    }
+    const footer = formatAskFooter(result);
+    return {
+        ok: true,
+        message: options.stream ? footer : `${result.answer}${footer}`,
+        data: result,
+        json: {
+            ok: true,
+            ...result,
+        },
+    };
+}
+export async function runAskCommand(config, args, options = {}) {
+    const action = args[1];
+    const actionArgs = args.slice(2);
+    if (action === 'history') {
+        return handleHistory(config, actionArgs);
+    }
+    if (action === 'show') {
+        return handleShow(config, actionArgs);
+    }
+    return handleQuestion(config, args.slice(1), options);
+}

package/dist/commands/auth.js

@@ -1,5 +1,5 @@
 import { saveKiipuConfig } from '../config/config.js';
-import { createAuthState, createLoopbackServer, createPkcePair, getDefaultDeviceName, openBrowser, waitForEnterBeforeOpeningBrowser } from '../lib/browser-auth.js';
+import { createAuthState, createLoopbackServer, createPkcePair, getDefaultDeviceName, openBrowser, waitForEnterBeforeOpeningBrowser, } from '../lib/browser-auth.js';
 import { KiipuUserApiClient } from '../lib/kiipu-user-client.js';
 import { logCliEvent } from '../logger/cli-logger.js';
 async function storeAuthenticatedConfig(config, payload) {

package/dist/commands/doctor.js

@@ -14,11 +14,15 @@ export async function runDoctorCommand(config) {
     const checks = [];
     let ok = true;
     const apiBaseUrlConfig = getConfiguredApiBaseUrl();
-    checks.push(config.apiKey ? `OK API key: ${config.keyPrefix ?? 'configured'}` : 'Missing API key. Run `kiipu auth login`.');
+    checks.push(config.apiKey
+        ? `OK API key: ${config.keyPrefix ?? 'configured'}`
+        : 'Missing API key. Run `kiipu auth login`.');
     if (!(config.apiKey || process.env.KIIPU_API_KEY)) {
         ok = false;
     }
-    checks.push(config.apiKey || process.env.KIIPU_API_KEY ? 'OK post API auth: configured' : 'Missing API key for post requests.');
+    checks.push(config.apiKey || process.env.KIIPU_API_KEY
+        ? 'OK note API auth: configured'
+        : 'Missing API key for note requests.');
     checks.push(apiBaseUrlConfig.source === 'env'
         ? `WARN API base URL override: ${config.apiBaseUrl}`
         : `OK API base URL: ${config.apiBaseUrl}`);
@@ -42,7 +46,9 @@ export async function runDoctorCommand(config) {
         if (!authStatus.ok) {
             ok = false;
         }
-        checks.push(authStatus.ok ? `OK API key auth: ${authStatus.data.username}` : `API key auth failed: ${authStatus.error.message}`);
+        checks.push(authStatus.ok
+            ? `OK API key auth: ${authStatus.data.username}`
+            : `API key auth failed: ${authStatus.error.message}`);
     }
     try {
         await access(configPath);

package/dist/commands/help.js

@@ -2,64 +2,98 @@ function block(lines) {
     return lines.join('\n');
 }
 export function getHelpResult(command) {
-    if (command === 'post') {
+    if (command === 'ask') {
         return {
             ok: true,
             message: block([
                 'Kiipu CLI',
                 '',
                 'Usage:',
-                '  kiipu post create --content "<text>"',
-                '  kiipu post create "<text>"',
-                '  kiipu post list [--tag <tag>] [--sort <updatedAt|createdAt|title>] [--starred] [--deleted]',
-                '  kiipu post search <query>',
-                '  kiipu post search --query "<query>"',
-                '  kiipu post show --id <postId>',
-                '  kiipu post update --id <postId> --content "<text>" [--title "<title>"] [--visibility public|private] [--tags <a,b,c>]',
-                '  kiipu post star --id <postId>',
-                '  kiipu post pin --id <postId>',
-                '  kiipu post delete --id <postId>',
-                '  kiipu post restore --id <postId>',
-                '  kiipu post purge --id <postId>',
+                '  kiipu ask "question"',
+                '  kiipu ask --question "question"',
+                '  kiipu ask --conversation-id <conversationId> "follow-up"',
+                '  kiipu ask history [--query <q>] [--limit <n>] [--archived]',
+                '  kiipu ask show --id <conversationId>',
                 '',
                 'Description:',
-                '  Run direct Kiipu post actions from the local CLI.',
+                '  Ask questions over your Kiipu notes using the same conversation-aware Ask surface as the web app.',
+                '',
+                'Options:',
+                '  --question "<text>"        Question to ask when not using a positional argument',
+                '  --conversation-id <id>     Continue an existing Ask conversation',
+                '  --top-k <1-20>             Optional retrieval count for Ask',
+                '  --source-mode <value>      One of fresh or locked',
+                '  --query "<query>"          Filter Ask history rows',
+                '  --limit <1-50>             Limit Ask history rows',
+                '  --archived                 List archived Ask conversations',
+                '  --id <conversationId>      Conversation id for ask show',
+                '',
+                'Examples:',
+                '  kiipu ask "What did I save about the roadmap?"',
+                '  kiipu ask --conversation-id conv_123 "What should I do next?"',
+                '  kiipu ask history --limit 10',
+                '  kiipu ask show --id conv_123',
+            ]),
+        };
+    }
+    if (command === 'note') {
+        return {
+            ok: true,
+            message: block([
+                'Kiipu CLI',
+                '',
+                'Usage:',
+                '  kiipu note create --content "<text>"',
+                '  kiipu note create "<text>"',
+                '  kiipu note list [--tag <tag>] [--sort <updatedAt|createdAt|title>] [--starred] [--deleted]',
+                '  kiipu note search <query>',
+                '  kiipu note search --query "<query>"',
+                '  kiipu note show --id <noteId>',
+                '  kiipu note update --id <noteId> --content "<text>" [--title "<title>"] [--visibility public|private] [--tags <a,b,c>]',
+                '  kiipu note star --id <noteId>',
+                '  kiipu note pin --id <noteId>',
+                '  kiipu note delete --id <noteId>',
+                '  kiipu note restore --id <noteId>',
+                '  kiipu note purge --id <noteId>',
+                '',
+                'Description:',
+                '  Run direct Kiipu note actions from the local CLI.',
                 '',
                 'Actions:',
-                '  create      Create a new post',
-                '  list        List your published, starred, or deleted posts',
-                '  search      Search your published posts',
-                '  show        Show one post with full metadata',
-                '  update      Update post content and metadata',
-                '  star        Toggle a post star',
-                '  pin         Toggle a post pin',
-                '  delete      Soft-delete an existing post by explicit id',
-                '  restore     Restore a deleted post by explicit id',
-                '  purge       Permanently delete a post by explicit id',
+                '  create      Create a new note',
+                '  list        List your active, starred, or deleted notes',
+                '  search      Search your active notes',
+                '  show        Show one note with full metadata',
+                '  update      Update note content and metadata',
+                '  star        Toggle a note star',
+                '  pin         Toggle a note pin',
+                '  delete      Soft-delete an existing note by explicit id',
+                '  restore     Restore a deleted note by explicit id',
+                '  purge       Permanently delete a note by explicit id',
                 '',
                 'Options:',
-                '  --content "<text>"         Post content for create',
-                '  --id <postId>              Required for show, update, star, pin, delete, restore, and purge',
-                '  --query "<query>"          Search query for post search',
-                '  --tag <tag>                Filter post list results by tag',
+                '  --content "<text>"         Note content for create',
+                '  --id <noteId>              Required for show, update, star, pin, delete, restore, and purge',
+                '  --query "<query>"          Search query for note search',
+                '  --tag <tag>                Filter note list results by tag',
                 '  --sort <field>             One of updatedAt, createdAt, or title',
-                '  --starred                  List only starred posts',
-                '  --deleted                  List only deleted posts',
-                '  --title "<title>"          Optional title for post update',
-                '  --visibility <value>       Optional visibility for post update',
-                '  --tags <a,b,c>             Optional comma-separated tags for post update',
+                '  --starred                  List only starred notes',
+                '  --deleted                  List only deleted notes',
+                '  --title "<title>"          Optional title for note update',
+                '  --visibility <value>       Optional visibility for note update',
+                '  --tags <a,b,c>             Optional comma-separated tags for note update',
                 '',
                 'Examples:',
-                '  kiipu post create "Hello Kiipu"',
-                '  kiipu post list --sort updatedAt',
-                '  kiipu post search "roadmap"',
-                '  kiipu post show --id 123',
-                '  kiipu post update --id 123 --content "Updated text" --tags work,#notes',
-                '  kiipu post star --id 123',
-                '  kiipu post pin --id 123',
-                '  kiipu post create --content "Hello Kiipu"',
-                '  kiipu post delete --id 123',
-                '  kiipu post restore --id 123',
+                '  kiipu note create "Hello Kiipu"',
+                '  kiipu note list --sort updatedAt',
+                '  kiipu note search "roadmap"',
+                '  kiipu note show --id 123',
+                '  kiipu note update --id 123 --content "Updated text" --tags work,#notes',
+                '  kiipu note star --id 123',
+                '  kiipu note pin --id 123',
+                '  kiipu note create --content "Hello Kiipu"',
+                '  kiipu note delete --id 123',
+                '  kiipu note restore --id 123',
             ]),
         };
     }
@@ -139,16 +173,19 @@ export function getHelpResult(command) {
             '  kiipu <command> [options]',
             '',
             'Core commands:',
-            '  post               Create, browse, update, and delete posts with direct CLI arguments',
+            '  ask                Ask questions over your Kiipu notes and browse Ask conversations',
+            '  note               Create, browse, update, and delete notes with direct CLI arguments',
             '  auth               Manage local API key authentication',
             '  doctor             Check local setup, API access, and wrapper readiness',
             '  skills             Show where the Claude Code plugin package lives',
             '',
             'Core examples:',
-            '  kiipu post create "Hello Kiipu"',
-            '  kiipu post list --starred',
-            '  kiipu post search "Hello"',
-            '  kiipu post delete --id 123',
+            '  kiipu ask "What changed in my roadmap notes?"',
+            '  kiipu ask history --limit 10',
+            '  kiipu note create "Hello Kiipu"',
+            '  kiipu note list --starred',
+            '  kiipu note search "Hello"',
+            '  kiipu note delete --id 123',
             '  kiipu auth login',
             '  kiipu doctor',
             '  claude --plugin-dir ./packages/claude-plugin',