@otoreach/telmeeh-cli 1.0.0

package/README.md

@@ -0,0 +1,58 @@
+# @telmeeh/cli
+
+Telmeeh from your terminal — search, fetch, create, and improve prompts and agent
+skills, and install a Telmeeh skill into your AI assistant.
+
+## Install
+
+```bash
+npm install -g @telmeeh/cli
+```
+
+On install you'll be asked which AI assistant(s) to add the Telmeeh agent skill to
+(Claude Code, Cursor, Windsurf, …). You can re-run this anytime with
+`telmeeh skills install`.
+
+## Authenticate
+
+Create an API key in **Settings → API Keys** in the Telmeeh dashboard, then:
+
+```bash
+telmeeh auth login            # prompts for your tk_live_… key
+telmeeh auth whoami           # confirm who you are
+```
+
+The key is stored in `~/.telmeeh/config.json` (mode `0600`). You can also set
+`TELMEEH_API_KEY` and `TELMEEH_API_URL` environment variables, or pass `--key` /
+`--api-url` per command.
+
+## Commands
+
+```bash
+telmeeh categories list
+
+telmeeh prompts list [--view all|starred|recent|uncategorized] [--category <id>]
+telmeeh prompts search <query>
+telmeeh prompts get <id>
+telmeeh prompts create --title <t> --content <text|->  [--category <id>] [--starred]
+telmeeh prompts improve <text|-> [--context <c>]
+
+telmeeh skills list [--view ...] [--category <id>]
+telmeeh skills search <query>
+telmeeh skills get <id>
+telmeeh skills create --name <n> [--desc <d>] [--category <id>]
+telmeeh skills update <id> [--name <n>] [--desc <d>] [--file remote=local.md] [--note <n>]
+telmeeh skills generate --goal <g> [--context <c>] [--category <id>]
+telmeeh skills export <id> [--out <dir>]
+telmeeh skills install
+```
+
+Use `-` for `--content`/`<text>` to read from stdin, and `--json` for raw JSON output.
+
+## Development
+
+```bash
+pnpm install
+pnpm dev -- prompts list   # run from source with tsx
+pnpm build                 # compile to dist/
+```

package/dist/client.js

@@ -0,0 +1,98 @@
+import { resolveConfig } from './config.js';
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(status, message, body) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+        this.body = body;
+    }
+}
+/** Thrown when no API key is configured. */
+export class NotAuthenticatedError extends Error {
+    constructor() {
+        super('Not authenticated. Run `telmeeh auth login` first.');
+        this.name = 'NotAuthenticatedError';
+    }
+}
+function buildUrl(base, path, query) {
+    const url = new URL(path, base + '/');
+    if (query) {
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined && value !== null && value !== '') {
+                url.searchParams.set(key, String(value));
+            }
+        }
+    }
+    return url.toString();
+}
+async function parseError(res) {
+    let body = undefined;
+    let message = `Request failed (${res.status})`;
+    try {
+        body = await res.json();
+        if (body && typeof body === 'object' && 'error' in body) {
+            message = String(body.error);
+        }
+    }
+    catch {
+        /* non-JSON body */
+    }
+    if (res.status === 401) {
+        message = 'Unauthorized — your API key is missing or invalid. Run `telmeeh auth login`.';
+    }
+    else if (res.status === 429) {
+        const reset = body?.resetTime
+            ?? body?.rateLimit?.resetTime;
+        const when = reset ? ` Resets at ${new Date(reset).toLocaleString()}.` : '';
+        message = `Rate limit exceeded.${when}`;
+    }
+    return new ApiError(res.status, message, body);
+}
+export class TelmeehClient {
+    apiKey;
+    apiUrl;
+    constructor(options = {}) {
+        const cfg = resolveConfig(options);
+        this.apiKey = cfg.apiKey;
+        this.apiUrl = cfg.apiUrl;
+    }
+    get baseUrl() {
+        return this.apiUrl;
+    }
+    headers(extra) {
+        if (!this.apiKey)
+            throw new NotAuthenticatedError();
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+            ...extra,
+        };
+    }
+    async get(path, query) {
+        const res = await fetch(buildUrl(this.apiUrl, path, query), {
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            throw await parseError(res);
+        return (await res.json());
+    }
+    async getBuffer(path, query) {
+        const res = await fetch(buildUrl(this.apiUrl, path, query), {
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            throw await parseError(res);
+        return Buffer.from(await res.arrayBuffer());
+    }
+    async post(path, body) {
+        const res = await fetch(buildUrl(this.apiUrl, path), {
+            method: 'POST',
+            headers: this.headers({ 'Content-Type': 'application/json' }),
+            body: JSON.stringify(body ?? {}),
+        });
+        if (!res.ok)
+            throw await parseError(res);
+        return (await res.json());
+    }
+}

package/dist/commands/auth.js

@@ -0,0 +1,78 @@
+import * as p from '@clack/prompts';
+import { TelmeehClient } from '../client.js';
+import { resolveConfig, writeStoredConfig, readStoredConfig, clearApiKey } from '../config.js';
+import { wantsJson, printJson, success, fail, info } from '../output.js';
+export function registerAuth(program) {
+    const auth = program.command('auth').description('Manage CLI authentication');
+    auth
+        .command('login')
+        .description('Save and validate your Telmeeh API key')
+        .option('-k, --key <key>', 'API key (tk_live_…). Omit to be prompted.')
+        .action(async (opts) => {
+        const globals = program.opts();
+        // The global `--key` option captures `--key` passed after the subcommand,
+        // so check both the subcommand option and the global.
+        let key = opts.key || globals.key;
+        if (!key) {
+            if (!process.stdin.isTTY) {
+                fail('No API key provided. Pass --key tk_live_… (no interactive terminal available).');
+                process.exit(1);
+            }
+            const entered = await p.password({
+                message: 'Paste your Telmeeh API key (tk_live_…)',
+                validate: (v) => (v.startsWith('tk_live_') ? undefined : 'Keys start with tk_live_'),
+            });
+            if (p.isCancel(entered)) {
+                info('Cancelled.');
+                process.exit(1);
+            }
+            key = entered;
+        }
+        const client = new TelmeehClient({ apiKey: key, apiUrl: globals.apiUrl });
+        let me;
+        try {
+            me = await client.get('api/cli/whoami');
+        }
+        catch (err) {
+            const e = err;
+            if (e.status === 404) {
+                fail(`Could not validate key: the server at ${client.baseUrl} does not expose /api/cli/whoami yet. ` +
+                    `Deploy the latest backend, or point at a server that has it (e.g. --api-url http://localhost:3000).`);
+            }
+            else {
+                fail(`Could not validate key: ${e.message}`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const cfg = resolveConfig({ apiUrl: globals.apiUrl });
+        const stored = readStoredConfig();
+        stored.apiKey = key;
+        if (globals.apiUrl)
+            stored.apiUrl = cfg.apiUrl;
+        writeStoredConfig(stored);
+        success(`Logged in as ${me.user.email} — team "${me.team.name}" (${me.team.plan})`);
+    });
+    auth
+        .command('logout')
+        .description('Remove the stored API key')
+        .action(() => {
+        clearApiKey();
+        success('Logged out. Stored API key removed.');
+    });
+    auth
+        .command('whoami')
+        .description('Show the currently authenticated identity')
+        .action(async () => {
+        const globals = program.opts();
+        const client = new TelmeehClient({ apiKey: globals.key, apiUrl: globals.apiUrl });
+        const me = await client.get('api/cli/whoami');
+        if (wantsJson()) {
+            printJson(me);
+            return;
+        }
+        info(`Email: ${me.user.email}`);
+        info(`Team:  ${me.team.name} (id ${me.team.id})`);
+        info(`Plan:  ${me.team.plan}`);
+    });
+}

package/dist/commands/categories.js

@@ -0,0 +1,26 @@
+import { TelmeehClient } from '../client.js';
+import { wantsJson, printJson, printTable } from '../output.js';
+function clientFrom(program) {
+    const g = program.opts();
+    return new TelmeehClient({ apiKey: g.key, apiUrl: g.apiUrl });
+}
+export function registerCategories(program) {
+    const cmd = program.command('categories').description('Browse your categories');
+    cmd
+        .command('list')
+        .alias('ls')
+        .description('List all categories')
+        .action(async () => {
+        const client = clientFrom(program);
+        const data = await client.get('api/categories/list');
+        if (wantsJson()) {
+            printJson(data.categories);
+            return;
+        }
+        printTable(data.categories, [
+            ['ID', (c) => c.id],
+            ['NAME', (c) => c.name, 40],
+            ['ITEMS', (c) => c.filesCount],
+        ]);
+    });
+}

package/dist/commands/prompts.js

@@ -0,0 +1,110 @@
+import { readFileSync } from 'node:fs';
+import { TelmeehClient } from '../client.js';
+import { wantsJson, printJson, printTable, success, info } from '../output.js';
+function clientFrom(program) {
+    const g = program.opts();
+    return new TelmeehClient({ apiKey: g.key, apiUrl: g.apiUrl });
+}
+/** Read `value` directly, or from stdin when value is "-". */
+function readMaybeStdin(value) {
+    if (value === '-')
+        return readFileSync(0, 'utf8').trim();
+    return value;
+}
+function printPromptList(data) {
+    if (wantsJson()) {
+        printJson(data.prompts);
+        return;
+    }
+    printTable(data.prompts, [
+        ['ID', (p) => p.id],
+        ['★', (p) => (p.starred ? '★' : '')],
+        ['TITLE', (p) => p.title, 50],
+        ['CATEGORY', (p) => p.categoryName ?? '', 20],
+    ]);
+}
+export function registerPrompts(program) {
+    const cmd = program.command('prompts').description('Manage your prompts');
+    cmd
+        .command('list')
+        .alias('ls')
+        .description('List prompts')
+        .option('--view <view>', 'all | starred | recent | uncategorized', 'all')
+        .option('--category <id>', 'filter by category id')
+        .option('--page <n>', 'page number', '1')
+        .option('--page-size <n>', 'results per page', '50')
+        .action(async (opts) => {
+        const client = clientFrom(program);
+        const data = await client.get('api/prompts/list', {
+            view: opts.view,
+            categoryId: opts.category,
+            page: opts.page,
+            pageSize: opts.pageSize,
+        });
+        printPromptList(data);
+    });
+    cmd
+        .command('search <query>')
+        .description('Search prompts by title/content')
+        .action(async (query) => {
+        const client = clientFrom(program);
+        const data = await client.get('api/prompts/list', { search: query });
+        printPromptList(data);
+    });
+    cmd
+        .command('get <id>')
+        .description('Show a prompt\'s full content')
+        .action(async (id) => {
+        const client = clientFrom(program);
+        const data = await client.get('api/prompts/get', {
+            id,
+        });
+        if (wantsJson()) {
+            printJson(data.prompt);
+            return;
+        }
+        const p = data.prompt;
+        info(`# ${p.title}  (id ${p.id}${p.categoryName ? `, ${p.categoryName}` : ''})`);
+        process.stdout.write(p.content + '\n');
+    });
+    cmd
+        .command('create')
+        .description('Create a new prompt')
+        .requiredOption('--title <title>', 'prompt title')
+        .requiredOption('--content <content|->', 'prompt content, or "-" to read stdin')
+        .option('--category <id>', 'category id')
+        .option('--starred', 'mark as starred')
+        .action(async (opts) => {
+        const client = clientFrom(program);
+        const data = await client.post('api/prompts/create', {
+            title: opts.title,
+            content: readMaybeStdin(opts.content),
+            categoryId: opts.category ? Number(opts.category) : undefined,
+            starred: Boolean(opts.starred),
+        });
+        if (wantsJson()) {
+            printJson(data.prompt);
+            return;
+        }
+        success(`Created prompt "${data.prompt.title}" (id ${data.prompt.id})`);
+    });
+    cmd
+        .command('improve <text|->')
+        .description('Run text through the Telmeeh AI improver')
+        .option('--context <context>', 'extra context for the improver')
+        .action(async (text, opts) => {
+        const client = clientFrom(program);
+        const data = await client.post('api/extension/improve', {
+            content: readMaybeStdin(text),
+            context: opts.context,
+        });
+        if (wantsJson()) {
+            printJson(data);
+            return;
+        }
+        process.stdout.write(data.improvedContent + '\n');
+        if (data.rateLimit?.remaining !== undefined) {
+            info(`Improvements remaining: ${data.rateLimit.remaining}`);
+        }
+    });
+}

package/dist/commands/skills.js

@@ -0,0 +1,151 @@
+import { resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import AdmZip from 'adm-zip';
+import { TelmeehClient } from '../client.js';
+import { wantsJson, printJson, printTable, success, info } from '../output.js';
+import { runInstaller } from '../installer.js';
+function clientFrom(program) {
+    const g = program.opts();
+    return new TelmeehClient({ apiKey: g.key, apiUrl: g.apiUrl });
+}
+function printSkillList(data) {
+    if (wantsJson()) {
+        printJson(data.skills);
+        return;
+    }
+    printTable(data.skills, [
+        ['ID', (s) => s.id],
+        ['NAME', (s) => s.name, 40],
+        ['FILES', (s) => s.fileCount ?? ''],
+        ['DESCRIPTION', (s) => s.description ?? '', 50],
+    ]);
+}
+/** Parse repeated `--file path=./local.md` flags into {path, content}. */
+function collectFiles(value, acc) {
+    const eq = value.indexOf('=');
+    if (eq === -1) {
+        throw new Error(`--file expects "remotePath=localFile", got "${value}"`);
+    }
+    const path = value.slice(0, eq).trim();
+    const localFile = value.slice(eq + 1).trim();
+    acc.push({ path, content: readFileSync(localFile, 'utf8') });
+    return acc;
+}
+export function registerSkills(program) {
+    const cmd = program.command('skills').description('Manage your agent skills');
+    cmd
+        .command('list')
+        .alias('ls')
+        .description('List skills')
+        .option('--view <view>', 'all | starred | recent | uncategorized', 'all')
+        .option('--category <id>', 'filter by category id')
+        .action(async (opts) => {
+        const client = clientFrom(program);
+        const data = await client.get('api/skills/list', {
+            view: opts.view,
+            categoryId: opts.category,
+        });
+        printSkillList(data);
+    });
+    cmd
+        .command('search <query>')
+        .description('Search skills by name')
+        .action(async (query) => {
+        const client = clientFrom(program);
+        const data = await client.get('api/skills/list', { search: query });
+        printSkillList(data);
+    });
+    cmd
+        .command('get <id>')
+        .description('Show a skill\'s files')
+        .action(async (id) => {
+        const client = clientFrom(program);
+        const data = await client.get('api/skills/files', {
+            skillId: id,
+        });
+        if (wantsJson()) {
+            printJson(data.files);
+            return;
+        }
+        for (const file of data.files) {
+            info(`\n=== ${file.path} ===`);
+            process.stdout.write(file.content + '\n');
+        }
+    });
+    cmd
+        .command('create')
+        .description('Create a new skill')
+        .requiredOption('--name <name>', 'skill name')
+        .option('--desc <description>', 'short description')
+        .option('--category <id>', 'category id')
+        .action(async (opts) => {
+        const client = clientFrom(program);
+        const data = await client.post('api/skills/create', {
+            name: opts.name,
+            description: opts.desc,
+            categoryId: opts.category ? Number(opts.category) : undefined,
+        });
+        if (wantsJson()) {
+            printJson(data.skill);
+            return;
+        }
+        success(`Created skill "${data.skill.name}" (id ${data.skill.id})`);
+    });
+    cmd
+        .command('update <id>')
+        .description('Update a skill (metadata and/or files)')
+        .option('--name <name>', 'new name')
+        .option('--desc <description>', 'new description')
+        .option('--category <id>', 'new category id')
+        .option('--file <path=localFile>', 'attach a file (repeatable)', collectFiles, [])
+        .option('--note <note>', 'change note for the version history')
+        .action(async (id, opts) => {
+        const client = clientFrom(program);
+        await client.post('api/skills/update', {
+            id: Number(id),
+            name: opts.name,
+            description: opts.desc,
+            categoryId: opts.category ? Number(opts.category) : undefined,
+            files: opts.file.length > 0 ? opts.file : undefined,
+            changeNote: opts.note,
+        });
+        success(`Updated skill ${id}`);
+    });
+    cmd
+        .command('generate')
+        .description('AI-generate a complete skill from a goal')
+        .requiredOption('--goal <goal>', 'what the skill should do')
+        .option('--context <context>', 'extra context')
+        .option('--category <id>', 'category id')
+        .action(async (opts) => {
+        const client = clientFrom(program);
+        const data = await client.post('api/skills/generate', {
+            goal: opts.goal,
+            context: opts.context,
+            categoryId: opts.category ? Number(opts.category) : undefined,
+        });
+        if (wantsJson()) {
+            printJson(data);
+            return;
+        }
+        success(`Generated skill "${data.skill.name}" (id ${data.skill.id}) with ${data.files.length} file(s)`);
+    });
+    cmd
+        .command('export <id>')
+        .description('Download a skill and extract its files to a directory')
+        .option('--out <dir>', 'output directory', '.')
+        .action(async (id, opts) => {
+        const client = clientFrom(program);
+        const buffer = await client.getBuffer('api/skills/export', { skillId: id });
+        const outDir = resolve(opts.out);
+        const zip = new AdmZip(buffer);
+        zip.extractAllTo(outDir, /* overwrite */ true);
+        success(`Extracted skill ${id} to ${outDir}`);
+    });
+    cmd
+        .command('install')
+        .description('Install the Telmeeh agent skill into your AI assistant(s)')
+        .action(async () => {
+        await runInstaller({ interactive: true });
+    });
+}

package/dist/config.js

@@ -0,0 +1,52 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, readFileSync, writeFileSync, existsSync, rmSync } from 'node:fs';
+export const DEFAULT_API_URL = 'https://telmeeh.com';
+function configDir() {
+    return join(homedir(), '.telmeeh');
+}
+function configPath() {
+    return join(configDir(), 'config.json');
+}
+export function readStoredConfig() {
+    try {
+        const raw = readFileSync(configPath(), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+export function writeStoredConfig(config) {
+    const dir = configDir();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    writeFileSync(configPath(), JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+export function clearApiKey() {
+    const config = readStoredConfig();
+    delete config.apiKey;
+    if (Object.keys(config).length === 0) {
+        try {
+            rmSync(configPath());
+        }
+        catch {
+            /* ignore */
+        }
+        return;
+    }
+    writeStoredConfig(config);
+}
+/**
+ * Resolve config with precedence: explicit CLI flags > env vars > stored config > defaults.
+ */
+export function resolveConfig(overrides = {}) {
+    const stored = readStoredConfig();
+    const apiKey = overrides.apiKey || process.env.TELMEEH_API_KEY || stored.apiKey || undefined;
+    const apiUrl = (overrides.apiUrl ||
+        process.env.TELMEEH_API_URL ||
+        stored.apiUrl ||
+        DEFAULT_API_URL).replace(/\/+$/, '');
+    return { apiKey, apiUrl };
+}

package/dist/index.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { ApiError, NotAuthenticatedError } from './client.js';
+import { fail } from './output.js';
+import { registerAuth } from './commands/auth.js';
+import { registerCategories } from './commands/categories.js';
+import { registerPrompts } from './commands/prompts.js';
+import { registerSkills } from './commands/skills.js';
+const program = new Command();
+program
+    .name('telmeeh')
+    .description('Telmeeh CLI — manage your prompt & skill library from the terminal.')
+    .version('1.0.0')
+    .option('--json', 'output raw JSON (for scripting)')
+    .option('--api-url <url>', 'override the API base URL')
+    .option('--key <key>', 'override the API key for this command');
+registerAuth(program);
+registerCategories(program);
+registerPrompts(program);
+registerSkills(program);
+async function run() {
+    try {
+        await program.parseAsync(process.argv);
+    }
+    catch (err) {
+        if (err instanceof NotAuthenticatedError || err instanceof ApiError) {
+            fail(err.message);
+            process.exit(1);
+        }
+        fail(err.message || 'Unexpected error');
+        if (process.env.TELMEEH_DEBUG)
+            console.error(err);
+        process.exit(1);
+    }
+}
+void run();

package/dist/installer.js

@@ -0,0 +1,100 @@
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import * as p from '@clack/prompts';
+import { info, success } from './output.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Path to the bundled skill source (package root: skills/telmeeh/SKILL.md). */
+function bundledSkillPath() {
+    return join(__dirname, '..', 'skills', 'telmeeh', 'SKILL.md');
+}
+function buildTargets() {
+    const home = homedir();
+    return [
+        {
+            id: 'claude-code',
+            label: 'Claude Code  (~/.claude/skills/telmeeh/SKILL.md)',
+            detectDir: join(home, '.claude'),
+            dest: join(home, '.claude', 'skills', 'telmeeh', 'SKILL.md'),
+            format: 'skill',
+        },
+        {
+            id: 'cursor',
+            label: 'Cursor  (~/.cursor/rules/telmeeh.md)',
+            detectDir: join(home, '.cursor'),
+            dest: join(home, '.cursor', 'rules', 'telmeeh.md'),
+            format: 'rules',
+        },
+        {
+            id: 'windsurf',
+            label: 'Windsurf  (~/.codeium/windsurf/memories/telmeeh.md)',
+            detectDir: join(home, '.codeium', 'windsurf'),
+            dest: join(home, '.codeium', 'windsurf', 'memories', 'telmeeh.md'),
+            format: 'rules',
+        },
+        {
+            id: 'project',
+            label: 'This project  (./.claude/skills/telmeeh/SKILL.md)',
+            detectDir: process.cwd(),
+            dest: join(process.cwd(), '.claude', 'skills', 'telmeeh', 'SKILL.md'),
+            format: 'skill',
+        },
+    ];
+}
+/** Strip YAML frontmatter for agents that use plain-markdown rules. */
+function toRules(skillMarkdown) {
+    return skillMarkdown.replace(/^---\n[\s\S]*?\n---\n+/, '');
+}
+function writeTarget(target, source) {
+    const content = target.format === 'rules' ? toRules(source) : source;
+    mkdirSync(dirname(target.dest), { recursive: true });
+    writeFileSync(target.dest, content, 'utf8');
+}
+export async function runInstaller(options) {
+    const skillSrc = bundledSkillPath();
+    if (!existsSync(skillSrc)) {
+        info('Bundled Telmeeh skill not found; skipping skill installation.');
+        return;
+    }
+    const source = readFileSync(skillSrc, 'utf8');
+    const targets = buildTargets();
+    if (!options.interactive) {
+        info('Telmeeh agent skill is bundled. Run `telmeeh skills install` to add it to your AI assistant.');
+        return;
+    }
+    const detected = targets.filter((t) => existsSync(t.detectDir));
+    const choices = (detected.length > 0 ? detected : targets).map((t) => ({
+        value: t.id,
+        label: t.label,
+        hint: detected.includes(t) ? 'detected' : undefined,
+    }));
+    p.intro('Install the Telmeeh agent skill');
+    const selected = await p.multiselect({
+        message: 'Which AI assistant(s) should learn to use the Telmeeh CLI?',
+        options: choices,
+        required: false,
+    });
+    if (p.isCancel(selected) || !Array.isArray(selected) || selected.length === 0) {
+        p.outro('No assistants selected.');
+        return;
+    }
+    for (const id of selected) {
+        const target = targets.find((t) => t.id === id);
+        if (!target)
+            continue;
+        if (existsSync(target.dest)) {
+            const overwrite = await p.confirm({
+                message: `${target.dest} already exists. Overwrite?`,
+                initialValue: true,
+            });
+            if (p.isCancel(overwrite) || !overwrite) {
+                info(`Skipped ${target.label}`);
+                continue;
+            }
+        }
+        writeTarget(target, source);
+        success(`Installed → ${target.dest}`);
+    }
+    p.outro('Done. Ask your assistant to "use the Telmeeh CLI" to try it.');
+}

package/dist/output.js

@@ -0,0 +1,44 @@
+import pc from 'picocolors';
+/** Whether the current invocation requested raw JSON output (`--json`). */
+export function wantsJson() {
+    return process.argv.includes('--json');
+}
+export function printJson(data) {
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+export function info(msg) {
+    process.stderr.write(pc.dim(msg) + '\n');
+}
+export function success(msg) {
+    process.stderr.write(pc.green('✓ ') + msg + '\n');
+}
+export function fail(msg) {
+    process.stderr.write(pc.red('✗ ') + msg + '\n');
+}
+function truncate(value, max) {
+    const clean = value.replace(/\s+/g, ' ').trim();
+    return clean.length > max ? clean.slice(0, max - 1) + '…' : clean;
+}
+/**
+ * Render an array of records as a simple aligned table to stdout.
+ * Columns: [header, accessor, maxWidth].
+ */
+export function printTable(rows, columns) {
+    if (rows.length === 0) {
+        info('No results.');
+        return;
+    }
+    const headers = columns.map((c) => c[0]);
+    const cells = rows.map((row) => columns.map(([, accessor, max]) => {
+        const raw = accessor(row);
+        const str = raw === null || raw === undefined ? '' : String(raw);
+        return max ? truncate(str, max) : str;
+    }));
+    const widths = headers.map((h, i) => Math.max(h.length, ...cells.map((r) => r[i].length)));
+    const renderRow = (vals) => vals.map((v, i) => v.padEnd(widths[i])).join('  ');
+    process.stdout.write(pc.bold(renderRow(headers)) + '\n');
+    process.stdout.write(pc.dim(widths.map((w) => '─'.repeat(w)).join('  ')) + '\n');
+    for (const row of cells) {
+        process.stdout.write(renderRow(row) + '\n');
+    }
+}

package/dist/postinstall.js

@@ -0,0 +1,18 @@
+import { runInstaller } from './installer.js';
+/**
+ * Runs automatically after `npm i -g @telmeeh/cli`.
+ *
+ * Only prompts when attached to an interactive TTY and not in CI — otherwise
+ * it prints a hint and exits cleanly so package installs never hang or fail.
+ */
+async function main() {
+    const isCI = Boolean(process.env.CI);
+    const interactive = process.stdout.isTTY === true && process.stdin.isTTY === true && !isCI;
+    try {
+        await runInstaller({ interactive });
+    }
+    catch {
+        // Never let a postinstall failure break the package installation.
+    }
+}
+void main();

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@otoreach/telmeeh-cli",
+  "version": "1.0.0",
+  "description": "Telmeeh command-line tool — manage your prompt & skill library and AI agents from the terminal.",
+  "type": "module",
+  "bin": {
+    "telmeeh": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "clean": "rimraf dist",
+    "postinstall": "node dist/postinstall.js || true"
+  },
+  "keywords": [
+    "telmeeh",
+    "cli",
+    "prompts",
+    "ai",
+    "agent",
+    "skills"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "adm-zip": "^0.5.16",
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/adm-zip": "^0.5.7",
+    "@types/node": "^22.10.0",
+    "rimraf": "^6.0.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}

package/skills/telmeeh/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: telmeeh
+description: Use the Telmeeh CLI to search, fetch, create, and improve the user's prompt and skill library from the terminal. Trigger when the user mentions Telmeeh, asks to find/reuse one of their saved prompts, save a new prompt, improve a prompt, or work with their agent skills.
+---
+
+# Telmeeh CLI
+
+Telmeeh is the user's prompt & skill library. The `telmeeh` CLI exposes it from the
+terminal. Prefer it whenever the user wants to reuse, save, or improve prompts/skills
+instead of writing them from scratch.
+
+## Authentication
+
+Commands require a logged-in API key. If a command fails with an auth error, tell the
+user to run `telmeeh auth login` (it prompts for a `tk_live_…` key from
+Settings → API Keys in the Telmeeh dashboard). Check status with `telmeeh auth whoami`.
+
+Add `--json` to any command to get machine-readable output you can parse.
+
+## Common commands
+
+```bash
+# Categories
+telmeeh categories list
+
+# Prompts
+telmeeh prompts list                      # newest first
+telmeeh prompts search "cold email"       # full-text search
+telmeeh prompts get <id>                  # full content of one prompt
+telmeeh prompts create --title "T" --content -   # content from stdin
+telmeeh prompts improve "draft text"      # AI-improve text (rate limited)
+
+# Skills (reusable agent instruction packages)
+telmeeh skills list
+telmeeh skills search "summarize"
+telmeeh skills get <id>                   # print every file in the skill
+telmeeh skills generate --goal "review PRs"   # AI-generate a new skill
+telmeeh skills export <id> --out ./skill  # download + unzip files locally
+```
+
+## Recommended workflow
+
+1. **Before writing a prompt from scratch**, run `telmeeh prompts search "<topic>"` to
+   see if the user already has one. If a match exists, `telmeeh prompts get <id>` and
+   reuse/adapt it.
+2. **When the user crafts a good prompt**, offer to save it with `telmeeh prompts create`.
+3. **To sharpen a rough prompt**, pipe it through `telmeeh prompts improve`.
+4. **For repeatable multi-file instructions**, use skills: search first, then
+   `skills export` to pull files locally or `skills generate` to create a new one.
+
+Always pass `--json` when you need to read values (ids, content) programmatically.