depicta 0.9.0

package/bin/depicta.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Entry point shebang wrapper. Loads compiled output.
+import('../dist/index.js').catch((err) => {
+  console.error('Fatal: failed to load depicta:', err.message);
+  process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Depicta HTTP client — uses built-in fetch (Node 18+).
+ *
+ * All methods throw DepictaError on non-2xx responses.
+ * postJson returns a 3-tuple (body, status, headers) matching the Python
+ * reference so callers can read X-Depicta-Job-Id from headers.
+ *
+ * IMPORTANT: upload field name is "image" per contract.yaml spec.
+ */
+/** Response from postJson: [body, statusCode, headers]. */
+export type PostJsonResult = [Record<string, unknown>, number, Record<string, string>];
+/** Response from uploadFile. */
+export interface UploadResult {
+    image_url: string;
+}
+/**
+ * DepictaClient wraps the Depicta REST API with authentication.
+ * Uses Node 18+ global fetch. Timeout via AbortController.
+ */
+export declare class DepictaClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(apiKey: string, baseUrl: string, timeoutMs?: number);
+    /** Build Authorization header. */
+    private authHeaders;
+    /** Create an AbortController that times out after this.timeoutMs. */
+    private makeAbortController;
+    /**
+     * GET request. Returns parsed JSON body.
+     * Throws DepictaError on non-2xx status.
+     */
+    get(path_: string): Promise<Record<string, unknown>>;
+    /**
+     * GET request with query parameters.
+     */
+    getWithQuery(path_: string, params: Record<string, string>): Promise<Record<string, unknown>>;
+    /**
+     * POST JSON body. Returns [body, statusCode, headers].
+     * Headers map is lowercased. Throws DepictaError on non-2xx.
+     */
+    postJson(path_: string, body: Record<string, unknown>): Promise<PostJsonResult>;
+    /**
+     * Upload a local file via multipart/form-data.
+     * Field name MUST be "image" per contract.yaml spec.
+     * Returns the upload response with image_url.
+     */
+    uploadFile(path_: string, filePath: string): Promise<UploadResult>;
+    /**
+     * Download raw bytes from an absolute URL.
+     * Does not send auth headers — URLs are pre-signed.
+     */
+    downloadBytes(url: string): Promise<Buffer>;
+    /** Parse API error response and throw DepictaError. */
+    private throwApiError;
+    /** Wrap a fetch network error as a DepictaError with exit code 1. */
+    private wrapNetworkError;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,2DAA2D;AAC3D,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEvF,gCAAgC;AAChC,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAgB;IAMxE,kCAAkC;IAClC,OAAO,CAAC,WAAW;IAInB,qEAAqE;IACrE,OAAO,CAAC,mBAAmB;IAM3B;;;OAGG;IACG,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAkB1D;;OAEG;IACG,YAAY,CAChB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAKnC;;;OAGG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,cAAc,CAAC;IA0B1B;;;;OAIG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA6BxE;;;OAGG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAqBjD,uDAAuD;YACzC,aAAa;IAU3B,qEAAqE;IACrE,OAAO,CAAC,gBAAgB;CAIzB"}

package/dist/client.js

@@ -0,0 +1,163 @@
+/**
+ * Depicta HTTP client — uses built-in fetch (Node 18+).
+ *
+ * All methods throw DepictaError on non-2xx responses.
+ * postJson returns a 3-tuple (body, status, headers) matching the Python
+ * reference so callers can read X-Depicta-Job-Id from headers.
+ *
+ * IMPORTANT: upload field name is "image" per contract.yaml spec.
+ */
+import fs from 'fs';
+import path from 'path';
+import { DepictaError, errorFromResponse } from './errors.js';
+/**
+ * DepictaClient wraps the Depicta REST API with authentication.
+ * Uses Node 18+ global fetch. Timeout via AbortController.
+ */
+export class DepictaClient {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    constructor(apiKey, baseUrl, timeoutMs = 120_000) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.timeoutMs = timeoutMs;
+    }
+    /** Build Authorization header. */
+    authHeaders() {
+        return { Authorization: `Bearer ${this.apiKey}` };
+    }
+    /** Create an AbortController that times out after this.timeoutMs. */
+    makeAbortController() {
+        const ctrl = new AbortController();
+        setTimeout(() => ctrl.abort(), this.timeoutMs);
+        return ctrl;
+    }
+    /**
+     * GET request. Returns parsed JSON body.
+     * Throws DepictaError on non-2xx status.
+     */
+    async get(path_) {
+        const ctrl = this.makeAbortController();
+        let resp;
+        try {
+            resp = await fetch(this.baseUrl + path_, {
+                method: 'GET',
+                headers: this.authHeaders(),
+                signal: ctrl.signal,
+            });
+        }
+        catch (err) {
+            throw this.wrapNetworkError(err);
+        }
+        if (resp.status >= 400) {
+            await this.throwApiError(resp);
+        }
+        return (await resp.json());
+    }
+    /**
+     * GET request with query parameters.
+     */
+    async getWithQuery(path_, params) {
+        const qs = new URLSearchParams(params).toString();
+        return this.get(`${path_}?${qs}`);
+    }
+    /**
+     * POST JSON body. Returns [body, statusCode, headers].
+     * Headers map is lowercased. Throws DepictaError on non-2xx.
+     */
+    async postJson(path_, body) {
+        const ctrl = this.makeAbortController();
+        let resp;
+        try {
+            resp = await fetch(this.baseUrl + path_, {
+                method: 'POST',
+                headers: { ...this.authHeaders(), 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+                signal: ctrl.signal,
+            });
+        }
+        catch (err) {
+            throw this.wrapNetworkError(err);
+        }
+        if (resp.status >= 400) {
+            await this.throwApiError(resp);
+        }
+        const responseBody = (await resp.json());
+        const statusCode = resp.status;
+        // Collect all response headers as a lowercased map.
+        const headers = {};
+        resp.headers.forEach((value, key) => {
+            headers[key.toLowerCase()] = value;
+        });
+        return [responseBody, statusCode, headers];
+    }
+    /**
+     * Upload a local file via multipart/form-data.
+     * Field name MUST be "image" per contract.yaml spec.
+     * Returns the upload response with image_url.
+     */
+    async uploadFile(path_, filePath) {
+        const ctrl = new AbortController();
+        setTimeout(() => ctrl.abort(), 60_000);
+        const fileData = fs.readFileSync(filePath);
+        const filename = path.basename(filePath);
+        // Build multipart form data using FormData (available in Node 18+).
+        // CRITICAL: field name MUST be "image", not "file" — per contract.yaml upload.field_name.
+        const form = new FormData();
+        form.append('image', new Blob([fileData]), filename);
+        let resp;
+        try {
+            resp = await fetch(this.baseUrl + path_, {
+                method: 'POST',
+                headers: this.authHeaders(),
+                body: form,
+                signal: ctrl.signal,
+            });
+        }
+        catch (err) {
+            throw this.wrapNetworkError(err);
+        }
+        if (resp.status >= 400) {
+            await this.throwApiError(resp);
+        }
+        return (await resp.json());
+    }
+    /**
+     * Download raw bytes from an absolute URL.
+     * Does not send auth headers — URLs are pre-signed.
+     */
+    async downloadBytes(url) {
+        const ctrl = new AbortController();
+        setTimeout(() => ctrl.abort(), 60_000);
+        let resp;
+        try {
+            resp = await fetch(url, { signal: ctrl.signal });
+        }
+        catch (err) {
+            throw this.wrapNetworkError(err);
+        }
+        if (!resp.ok) {
+            throw new DepictaError(`Download failed: ${resp.status} ${resp.statusText}`, 'general_error', 1);
+        }
+        const ab = await resp.arrayBuffer();
+        return Buffer.from(ab);
+    }
+    /** Parse API error response and throw DepictaError. */
+    async throwApiError(resp) {
+        let body;
+        try {
+            body = (await resp.json());
+        }
+        catch {
+            body = { error: 'general_error', message: await resp.text() };
+        }
+        throw errorFromResponse(resp.status, body);
+    }
+    /** Wrap a fetch network error as a DepictaError with exit code 1. */
+    wrapNetworkError(err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return new DepictaError(msg, 'general_error', 1);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/commands/auth.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Auth commands: login, logout, status.
+ *
+ * login:   prompt for API key, validate against /v1/account/profile, store in config.
+ * logout:  remove api_key from config file.
+ * status:  show auth method and masked key; optionally verify via API.
+ *
+ * Config file is written with 0600 permissions (contract requirement, tested in auth.bats).
+ */
+import { Command } from 'commander';
+/** Register auth subcommands on the parent program. */
+export declare function registerAuthCommands(program: Command): void;
+//# sourceMappingURL=auth.d.ts.map

package/dist/commands/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqEpC,uDAAuD;AACvD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0H3D"}

package/dist/commands/auth.js

@@ -0,0 +1,188 @@
+/**
+ * Auth commands: login, logout, status.
+ *
+ * login:   prompt for API key, validate against /v1/account/profile, store in config.
+ * logout:  remove api_key from config file.
+ * status:  show auth method and masked key; optionally verify via API.
+ *
+ * Config file is written with 0600 permissions (contract requirement, tested in auth.bats).
+ */
+import { Command } from 'commander';
+import * as readline from 'readline';
+import { DepictaClient } from '../client.js';
+import { loadConfig, maskKey, resolveApiKey, resolveApiUrl, saveConfig, } from '../config.js';
+import { DepictaError, EXIT_AUTH } from '../errors.js';
+import { addGlobalFlags } from '../flags.js';
+import { detectMode, printError } from '../output.js';
+/** Prompt for a password-masked API key via readline. */
+async function promptApiKey() {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stderr,
+            terminal: true,
+        });
+        // Write the prompt to stderr so it doesn't pollute stdout.
+        process.stderr.write('API key: ');
+        // Hide input if terminal supports it.
+        if (process.stdin.isTTY) {
+            process.stdin.setRawMode?.(true);
+        }
+        let key = '';
+        process.stdin.on('data', (chunk) => {
+            const char = chunk.toString('utf8');
+            if (char === '\n' || char === '\r') {
+                if (process.stdin.isTTY) {
+                    process.stdin.setRawMode?.(false);
+                }
+                process.stderr.write('\n');
+                rl.close();
+                resolve(key);
+            }
+            else if (char === '\u0003') {
+                // Ctrl+C.
+                process.exit(1);
+            }
+            else if (char === '\u007f') {
+                // Backspace.
+                key = key.slice(0, -1);
+            }
+            else {
+                key += char;
+            }
+        });
+    });
+}
+/** Read the API key: masked prompt if TTY, readline if piped (for tests). */
+async function readApiKey() {
+    if (process.stdin.isTTY) {
+        return promptApiKey();
+    }
+    // Non-TTY (test): read one line from stdin.
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({ input: process.stdin });
+        rl.once('line', (line) => {
+            rl.close();
+            resolve(line.trim());
+        });
+    });
+}
+/** Register auth subcommands on the parent program. */
+export function registerAuthCommands(program) {
+    const auth = new Command('auth')
+        .description('Manage authentication')
+        .addHelpCommand(false);
+    // --- auth login ---
+    const loginCmd = new Command('login').description('Configure API key');
+    addGlobalFlags(loginCmd);
+    loginCmd.action(async (opts) => {
+        const mode = detectMode({ forceJson: opts.json, forceHuman: opts.human });
+        process.stderr.write('Get your API key at https://depicta.ai/dashboard/api-keys\n');
+        const key = await readApiKey();
+        if (!key) {
+            const err = new DepictaError('No API key provided', 'authentication_error', EXIT_AUTH);
+            printError(err.toDict(), mode);
+            process.exit(EXIT_AUTH);
+        }
+        const url = resolveApiUrl(opts.apiUrl);
+        const client = new DepictaClient(key, url);
+        let profile;
+        try {
+            profile = await client.get('/v1/account/profile');
+        }
+        catch (err) {
+            if (err instanceof DepictaError) {
+                printError(err.toDict(), mode);
+                process.exit(err.exitCode);
+            }
+            throw err;
+        }
+        // Extract email from nested user object.
+        const user = profile['user'];
+        const email = typeof user?.['email'] === 'string' ? user['email'] : 'unknown';
+        // Store in config (creates file with 0600 permissions).
+        const cfg = loadConfig();
+        cfg['api_key'] = key;
+        saveConfig(cfg);
+        if (mode === 'json') {
+            process.stdout.write(JSON.stringify({ status: 'authenticated', email }) + '\n');
+        }
+        else if (!(opts.quiet ?? false)) {
+            process.stderr.write(`Authenticated as ${email}\n`);
+        }
+    });
+    // --- auth logout ---
+    const logoutCmd = new Command('logout').description('Remove stored credentials');
+    addGlobalFlags(logoutCmd);
+    logoutCmd.action(async (opts) => {
+        const mode = detectMode({ forceJson: opts.json, forceHuman: opts.human });
+        const cfg = loadConfig();
+        delete cfg['api_key'];
+        saveConfig(cfg);
+        if (mode === 'json') {
+            process.stdout.write(JSON.stringify({ status: 'logged_out' }) + '\n');
+        }
+        else if (!(opts.quiet ?? false)) {
+            process.stderr.write('Credentials removed.\n');
+        }
+    });
+    // --- auth status ---
+    const statusCmd = new Command('status').description('Show current auth state');
+    addGlobalFlags(statusCmd);
+    statusCmd.action(async (opts) => {
+        const mode = detectMode({ forceJson: opts.json, forceHuman: opts.human });
+        const key = resolveApiKey(opts.apiKey);
+        if (!key) {
+            if (mode === 'json') {
+                process.stdout.write(JSON.stringify({ method: 'none', authenticated: false }) + '\n');
+            }
+            else if (!(opts.quiet ?? false)) {
+                process.stderr.write('Not authenticated. Run depicta auth login\n');
+            }
+            return;
+        }
+        // Determine which source provided the key.
+        let method = 'config';
+        if (opts.apiKey)
+            method = 'flag';
+        else if (process.env['DEPICTA_API_KEY'])
+            method = 'env';
+        const masked = maskKey(key);
+        const url = resolveApiUrl(opts.apiUrl);
+        const client = new DepictaClient(key, url);
+        let email = null;
+        try {
+            const profile = await client.get('/v1/account/profile');
+            const user = profile['user'];
+            email = typeof user?.['email'] === 'string' ? user['email'] : null;
+        }
+        catch {
+            email = null;
+        }
+        if (mode === 'json') {
+            const result = {
+                method,
+                key_prefix: masked,
+                authenticated: email !== null,
+            };
+            if (email)
+                result['email'] = email;
+            process.stdout.write(JSON.stringify(result) + '\n');
+        }
+        else if (!(opts.quiet ?? false)) {
+            process.stderr.write(`Auth method: ${method}\n`);
+            process.stderr.write(`Key: ${masked}\n`);
+            if (email) {
+                process.stderr.write(`Account: ${email}\n`);
+            }
+            else {
+                process.stderr.write('Key is invalid\n');
+            }
+        }
+    });
+    auth.addCommand(loginCmd);
+    auth.addCommand(logoutCmd);
+    auth.addCommand(statusCmd);
+    program.addCommand(auth);
+}
+//# sourceMappingURL=auth.js.map

package/dist/commands/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"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"}

package/dist/commands/docs.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Docs command: output full CLI reference for LLMs and humans.
+ *
+ * Outputs the complete CLI_REFERENCE as JSON (--json / pipe) or
+ * formatted human-readable text (human mode / TTY).
+ */
+import { Command } from 'commander';
+/** Register the docs command on the parent program. */
+export declare function registerDocsCommand(program: Command): void;
+//# sourceMappingURL=docs.d.ts.map

package/dist/commands/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/commands/docs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsJpC,uDAAuD;AACvD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAa1D"}

package/dist/commands/docs.js

@@ -0,0 +1,165 @@
+/**
+ * Docs command: output full CLI reference for LLMs and humans.
+ *
+ * Outputs the complete CLI_REFERENCE as JSON (--json / pipe) or
+ * formatted human-readable text (human mode / TTY).
+ */
+import { Command } from 'commander';
+import { addGlobalFlags } from '../flags.js';
+import { detectMode } from '../output.js';
+/** Package version — kept in sync with package.json. */
+const VERSION = '0.9.0';
+/** Complete command reference — embedded so it works offline. */
+const CLI_REFERENCE = {
+    name: 'depicta',
+    version: VERSION,
+    description: 'Depicta CLI — AI image generation and processing from the terminal',
+    api_base_url: 'https://api.depicta.ai',
+    auth: {
+        env_var: 'DEPICTA_API_KEY',
+        config_file: '~/.config/depicta/config.json',
+        precedence: ['--api-key flag', 'DEPICTA_API_KEY env var', 'config file'],
+    },
+    output_modes: {
+        human: 'TTY detected or --human: Rich output to stderr, file path to stdout',
+        json: '--json flag: full JSON object to stdout',
+        pipe: 'non-TTY without --json: file path only to stdout (for piping)',
+    },
+    global_flags: {
+        '--json': 'Force JSON output',
+        '--human': 'Force human-readable output',
+        '--api-key <key>': 'Override API key for this call',
+        '--quiet / -q': 'Suppress informational output on stderr',
+    },
+    commands: {
+        'image <prompt>': {
+            description: 'Generate image from text',
+            flags: '--model/-m, --size/-s, --image-size, --output/-o, --output-dir/-d, --format/-f, --quality, --strictness',
+            output: 'JSON: {file, cost_eur, balance_eur, image_hash, model, ai_generated}',
+        },
+        'edit <input> <prompt>': {
+            description: 'Edit an existing image with a text prompt',
+            flags: 'same as image',
+            note: 'Input can be a file path, - (stdin), or URL',
+        },
+        'graphic <prompt>': {
+            description: 'Generate icon, logo, or clipart',
+            flags: 'same as image',
+        },
+        'diagram <prompt>': {
+            description: 'Generate a diagram',
+            flags: 'same as image + --type/-t (flowchart|sequence|architecture|mindmap|er|class|timeline|org-chart)',
+        },
+        'combine <images...>': {
+            description: 'Combine 2-5 images into one composition',
+            flags: 'same as image + --prompt/-p',
+        },
+        'story run <storyboard.json>': {
+            description: 'Generate multi-scene story from storyboard JSON (async, polls until complete)',
+            flags: '--output-dir/-d, --format/-f, --quality, --timeout',
+            output: 'JSON: {job_id, title, scenes: [{file, cost_eur}], total_cost_eur, balance_eur}',
+        },
+        'story status <job_id>': {
+            description: 'Poll status of an async story job',
+        },
+        'process crop <input>': {
+            description: 'Crop image',
+            flags: '--x, --y, --width, --height, --output/-o, --output-dir/-d',
+        },
+        'process resize <input>': { description: 'Resize image', flags: '--width, --height' },
+        'process convert <input>': { description: 'Convert format', flags: '--format/-f (png|jpg|webp)' },
+        'process optimize <input>': { description: 'Optimize compression', flags: '--colors, --min-psnr' },
+        'process remove-bg <input>': { description: 'Remove background' },
+        'process blur <input>': { description: 'Apply Gaussian blur', flags: '--radius' },
+        'process sharpen <input>': { description: 'Sharpen image', flags: '--amount, --threshold' },
+        'process adjust <input>': {
+            description: 'Adjust brightness/contrast/saturation',
+            flags: '--brightness, --contrast, --saturation',
+        },
+        'process grayscale <input>': { description: 'Convert to grayscale' },
+        'process invert <input>': { description: 'Invert colors' },
+        'process flip <input>': { description: 'Flip image', flags: '--direction (horizontal|vertical)' },
+        'process auto-orient <input>': { description: 'Auto-orient from EXIF' },
+        'process alpha-to-color <input>': {
+            description: 'Replace transparency with color',
+            flags: '--color (#RRGGBB)',
+        },
+        'process color-to-alpha <input>': {
+            description: 'Make color transparent',
+            flags: '--color, --tolerance',
+        },
+        'process rotate <input>': {
+            description: 'Rotate by angle',
+            flags: '--angle, --expand, --fill-color',
+        },
+        'process trim <input>': { description: 'Auto-trim borders', flags: '--tolerance' },
+        'process pad <input>': {
+            description: 'Add padding',
+            flags: '--width, --height, --color, --gravity',
+        },
+        'process metadata-strip <input>': { description: 'Strip metadata', flags: '--keep-icc' },
+        'process overlay <input>': {
+            description: 'Overlay image',
+            flags: '--overlay, --x, --y, --opacity',
+        },
+        'auth login': { description: 'Configure API key (interactive or piped)' },
+        'auth logout': { description: 'Remove stored credentials' },
+        'auth status': { description: 'Show current auth state' },
+        'guidelines search <query>': { description: 'Search content guidelines by keyword' },
+        'jobs list': { description: 'List recent generation jobs' },
+        'jobs get <job_id>': { description: 'Get a specific job by ID' },
+        models: { description: 'List available models' },
+        balance: { description: 'Show credit balance (balance_eur, held_eur)' },
+        version: { description: 'Show CLI version (no auth required)' },
+        docs: { description: 'Show this command reference' },
+    },
+    piping: {
+        convention: 'stdout = file path (pipe mode) or JSON (--json). stderr = display output.',
+        stdin: 'Use - as input argument to read file path from stdin',
+        example: 'depicta image \'a cat\' | depicta process remove-bg - | depicta process resize - --width 1200',
+    },
+    exit_codes: {
+        '0': 'success',
+        '1': 'general error',
+        '2': 'authentication error',
+        '3': 'insufficient credits',
+        '4': 'content rejected',
+        '5': 'rate limited',
+    },
+};
+/** Print a human-readable command reference to stderr. */
+function printHumanDocs() {
+    process.stderr.write(`Depicta CLI v${VERSION}\n\n`);
+    process.stderr.write('Commands:\n\n');
+    for (const [cmd, info] of Object.entries(CLI_REFERENCE.commands)) {
+        const desc = typeof info === 'object' && 'description' in info ? info.description : String(info);
+        process.stderr.write(`  depicta ${cmd}\n`);
+        process.stderr.write(`    ${desc}\n`);
+        if (typeof info === 'object' && 'flags' in info) {
+            process.stderr.write(`    Flags: ${info.flags}\n`);
+        }
+        process.stderr.write('\n');
+    }
+    process.stderr.write('Piping:\n');
+    process.stderr.write(`  ${CLI_REFERENCE.piping.example}\n\n`);
+    process.stderr.write('Exit codes:\n');
+    for (const [code, meaning] of Object.entries(CLI_REFERENCE.exit_codes)) {
+        process.stderr.write(`  ${code}: ${meaning}\n`);
+    }
+}
+/** Register the docs command on the parent program. */
+export function registerDocsCommand(program) {
+    const docsCmd = new Command('docs').description('Show complete CLI command reference');
+    addGlobalFlags(docsCmd);
+    docsCmd.action((opts) => {
+        const mode = detectMode({ forceJson: opts.json, forceHuman: opts.human });
+        if (mode === 'json' || mode === 'pipe') {
+            process.stdout.write(JSON.stringify(CLI_REFERENCE, null, 2) + '\n');
+        }
+        else {
+            printHumanDocs();
+        }
+    });
+    program.addCommand(docsCmd);
+}
+//# sourceMappingURL=docs.js.map

package/dist/commands/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../src/commands/docs.ts"],"names":[],"mappings":"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"}