@bergetai/odoo-cli 0.3.0 → 0.3.3

package/README.md

@@ -31,6 +31,9 @@ odoo helpdesk tickets list --team Support --json
 odoo project list --json
 odoo project tasks list --project "Content Pipeline" --open
 odoo project tasks show 850
+odoo documents tree --count
+odoo documents records list --folder "Product Backlog" --limit 20
+odoo documents records show 25
 
 # Mutations (support --dry-run)
 odoo crm leads create --name "New lead" --email info@example.com
@@ -52,6 +55,7 @@ Note: `odoo --version` prints the CLI's own version; `odoo version` queries the
 - Read-only Helpdesk surface (`helpdesk tickets list/show`) — `--open`/`--closed` via stage `fold`, strict team-scoped stage resolution, module-not-installed error (exit 4)
 - Read-only Project surface (`project list/show`) — `--user` (project manager) and `--tag` filters, archived projects excluded by default, module-not-installed error (exit 4)
 - Read-only Project task surface (`project tasks list/show`) — `--project` (required on list, resolved by name or id), project-scoped `--stage`, `--assignee` (many2many `user_ids`), `--tag`, `--priority` (0/Low, 1/High), `--open`/`--closed` via the task's `is_closed` flag, `--domain`/`--filter`, table/JSON output with `search_count` envelope, module-not-installed error (exit 4)
+- Documents surface (`documents`) — `tree` (hierarchical folder listing with `--count`/`--depth`/`--folder`), `records list/show` (folders excluded by default, `--type folder|binary|url|all`, `--folder`/`--owner`/`--partner`/`--tag`), `folders list`, `records create` (folder via `--folder-type folder`, link via `--link <url>`), `records update` (move via `--folder`), `records delete`, and `upload` (local file → base64 `datas`, MIME guessed from extension, `--dry-run` previews without sending bytes). Folders are `documents.document` rows with `type='folder'`; the hierarchy is `folder_id`. Module-not-installed error (exit 4)
 - Writes (`create`, `update`, `delete`) — single-call atomic batch `write`, client-side no-op diffing, delete convergence with `skipped` ids, post-failure "record may have been created" hint on `create`
 - `--dry-run` for all mutations — full validation, resolution, and before/after diffs without mutating
 - Internal notes (`add-note`) — creates internal Log Notes only (subtype_id=2, message_type=comment), **NEVER sends email to customer**, by design prevents accidental customer communication

package/dist/cli.js

@@ -4,7 +4,9 @@ import { authLoginCommand, authStatusCommand } from "./commands/auth.js";
 import { leadsCreateCommand, leadsDeleteCommand, leadsListCommand, leadsShowCommand, leadsUpdateCommand, crmLeads, } from "./commands/crm.js";
 import { ticketsCreateCommand, ticketsDeleteCommand, ticketsListCommand, ticketsShowCommand, ticketsUpdateCommand, helpdeskTickets, } from "./commands/helpdesk.js";
 import { addNoteCommand, listMessagesCommand, } from "./commands/notes.js";
+import { activitiesListCommand, activityDoneCommand, scheduleCommand, } from "./commands/activities.js";
 import { createTaskCommand, projectListCommand, projectShowCommand, tasksListCommand, tasksShowCommand, } from "./commands/project.js";
+import { documentsDocuments, documentsListCommand, foldersListCommand, documentsShowCommand, documentsCreateCommand, documentsUpdateCommand, documentsDeleteCommand, treeCommand, uploadCommand, } from "./commands/documents.js";
 import { versionCommand } from "./commands/version.js";
 import { CliError } from "./errors.js";
 import { applyGlobalOptions, enforceTransportSecurity, DEFAULT_TIMEOUT, } from "./global-options.js";
@@ -129,6 +131,100 @@ Examples:
         .action(async (ids) => {
         await run((g) => leadsDeleteCommand(ids, g), program);
     });
+    leads
+        .command("add-note")
+        .description("add an internal Log Note to a lead/opportunity (NEVER sends email)")
+        .argument("<id>", "record id")
+        .option("--body <text>", "note body (HTML allowed)")
+        .option("--body-file <path>", "read note body from file ('-' for stdin)")
+        .addHelpText("after", `
+IMPORTANT: This command creates INTERNAL notes only. These notes:
+  • Are NEVER sent to the customer via email
+  • Are only visible to internal users in Odoo
+  • Use subtype_id=2 (Note) and message_type=comment
+  • Cannot be used for customer-facing communication
+
+This is by design to prevent accidental customer emails.
+
+Examples:
+  $ odoo crm records add-note 338 --body "Internal note text"
+  $ odoo crm records add-note 338 --body-file note.md
+  $ cat note.md | odoo crm records add-note 338 --body-file -`)
+        .action(async (id, opts) => {
+        await run((g) => addNoteCommand(id, opts, g, "crm.lead"), program);
+    });
+    leads
+        .command("messages")
+        .description("list all messages for a record (emails, comments, notes)")
+        .argument("<id>", "record id")
+        .option("--limit <n>", "max messages to fetch", "50")
+        .option("--message-type <type>", "filter by message type (email, comment, notification)")
+        .option("--subtype <id>", "filter by subtype ID")
+        .option("--author <id>", "filter by author ID")
+        .option("--since <date>", "only messages after this date (YYYY-MM-DD HH:MM:SS)")
+        .addHelpText("after", `
+Examples:
+  # List all messages for lead 338
+  $ odoo crm records messages 338
+
+  # List only internal notes
+  $ odoo crm records messages 338 --subtype 2
+
+  # JSON output for scripting
+  $ odoo crm records messages 338 --json`)
+        .action(async (id, opts) => {
+        await run((g) => listMessagesCommand(id, opts, g, "crm.lead"), program);
+    });
+    leads
+        .command("schedule")
+        .description("schedule a new activity on a record (preview with --dry-run)")
+        .argument("<id>", "record id")
+        .requiredOption("--type <name|id>", "activity type (e.g. To-Do, Call, Meeting)")
+        .requiredOption("--deadline <yyyy-mm-dd>", "activity deadline")
+        .requiredOption("--summary <text>", "short summary (max 1 sentence)")
+        .option("--note <text>", "optional note (1-2 lines, point to the log)")
+        .option("--assignee <name|id>", "assignee (login, email, or name; default: you)")
+        .addHelpText("after", `
+A scheduled activity is the source of truth for a record's next step.
+An opportunity without a scheduled activity is a red flag.
+
+Examples:
+  $ odoo crm records schedule 338 --type "To-Do" --deadline 2026-08-25 \\
+      --summary "Send quote to Fredrik"
+  $ odoo crm records schedule 338 --type Meeting --deadline 2026-09-01 \\
+      --summary "Kickoff call" --assignee erik@berget.ai
+  $ odoo crm records schedule 338 --type "To-Do" --deadline 2026-08-25 \\
+      --summary "Send quote" --dry-run`)
+        .action(async (id, opts) => {
+        await run((g) => scheduleCommand(id, opts, g), program);
+    });
+    leads
+        .command("activities")
+        .description("list activities for a record")
+        .argument("<id>", "record id")
+        .option("--open", "only open (pending/planned) activities")
+        .option("--limit <n>", "max activities to fetch", "50")
+        .addHelpText("after", `
+Examples:
+  $ odoo crm records activities 338
+  $ odoo crm records activities 338 --open --json`)
+        .action(async (id, opts) => {
+        await run((g) => activitiesListCommand(id, opts, g), program);
+    });
+    leads
+        .command("activity-done")
+        .description("mark activities as done via action_done (preview with --dry-run)")
+        .argument("<id...>", "activity ids")
+        .addHelpText("after", `
+Uses action_done — the only reliable way to close an activity in Odoo
+(writing state='done' directly does not work).
+
+Examples:
+  $ odoo crm records activity-done 714
+  $ odoo crm records activity-done 714 721 --dry-run`)
+        .action(async (ids) => {
+        await run((g) => activityDoneCommand(ids, g), program);
+    });
     const helpdesk = program
         .command("helpdesk")
         .description("Helpdesk app (helpdesk.ticket, Enterprise)");
@@ -206,7 +302,7 @@ Examples:
   $ odoo helpdesk tickets add-note 398 --body-file note.md
   $ cat note.md | odoo helpdesk tickets add-note 398 --body-file -`)
         .action(async (id, opts) => {
-        await run((g) => addNoteCommand(id, opts, g), program);
+        await run((g) => addNoteCommand(id, opts, g, "helpdesk.ticket"), program);
     });
     tickets
         .command("messages")
@@ -234,7 +330,7 @@ Examples:
   # JSON output for scripting
   $ odoo helpdesk tickets messages 398 --json`)
         .action(async (id, opts) => {
-        await run((g) => listMessagesCommand(id, opts, g), program);
+        await run((g) => listMessagesCommand(id, opts, g, "helpdesk.ticket"), program);
     });
     const project = program
         .command("project")
@@ -328,6 +424,91 @@ Examples:
         .action(async (opts) => {
         await run((g) => createTaskCommand(opts, g), program);
     });
+    const documents = program
+        .command("documents")
+        .description("Documents app (documents.document, Enterprise)");
+    const records = documents
+        .command("records")
+        .description("files, links and folders");
+    records
+        .command("list")
+        .description("search and list documents (folders excluded by default)")
+        .option("--type <type>", "record type: document (default), folder, or all")
+        .option("--folder <name|id>", "only records directly in this folder (resolved by name)")
+        .option("--owner <name|id>", "filter by owner (login, email, or name)")
+        .option("--partner <name|id>", "filter by linked contact")
+        .option("--tag <name|id>", "filter by tag; repeatable, AND-ed", collect, [])
+        .option("--filter <f=v>", "equality filter; repeatable, AND-ed", collect, [])
+        .option("--domain <json>", "Odoo domain as a JSON array (mutually exclusive with --filter)")
+        .option("--fields <a,b,c>", "columns to display")
+        .option("--limit <n>", "max records (default: 50)", "50")
+        .option("--offset <n>", "skip the first n records", "0")
+        .option("--order <order>", 'sort order, e.g. "create_date desc"', undefined)
+        .action(async (opts) => {
+        await run((g) => documentsListCommand(opts, g), program);
+    });
+    records
+        .command("show")
+        .description("read one document or folder")
+        .argument("<id>", "record id")
+        .option("--fields <a,b,c>", "fields to display")
+        .option("--all-fields", "display every readable field")
+        .action(async (id, opts) => {
+        await run((g) => documentsShowCommand(id, opts, g), program);
+    });
+    addMutationFlags(records
+        .command("create")
+        .description("create a folder or URL link (preview with --dry-run; upload files via 'documents upload')"), documentsDocuments).action(async (opts) => {
+        await run((g) => documentsCreateCommand(opts, g), program);
+    });
+    addMutationFlags(records
+        .command("update")
+        .description("update documents (preview with --dry-run)"), documentsDocuments)
+        .argument("<id...>", "record ids")
+        .action(async (ids, opts) => {
+        await run((g) => documentsUpdateCommand(ids, opts, g), program);
+    });
+    records
+        .command("delete")
+        .description("delete documents (preview with --dry-run; unknown ids are skipped)")
+        .argument("<id...>", "record ids")
+        .action(async (ids) => {
+        await run((g) => documentsDeleteCommand(ids, g), program);
+    });
+    const folders = documents.command("folders").description("folders");
+    folders
+        .command("list")
+        .description("list all folders")
+        .option("--fields <a,b,c>", "columns to display")
+        .option("--limit <n>", "max records (default: 50)", "50")
+        .option("--offset <n>", "skip the first n records", "0")
+        .option("--order <order>", 'sort order, e.g. "name asc"', undefined)
+        .action(async (opts) => {
+        await run((g) => foldersListCommand(opts, g), program);
+    });
+    documents
+        .command("tree")
+        .description("print the folder tree with document counts")
+        .option("--folder <name|id>", "start from this folder (default: roots)")
+        .option("--depth <n>", "max depth", "10")
+        .option("--count", "show the number of documents per folder")
+        .action(async (opts) => {
+        await run((g) => treeCommand(opts, g), program);
+    });
+    documents
+        .command("upload")
+        .description("upload a local file as a document (preview with --dry-run)")
+        .requiredOption("--file <path>", "local file path ('-' for stdin)")
+        .option("--name <name>", "document name (default: file basename)")
+        .option("--folder <name|id>", "target folder (resolved by name)")
+        .option("--owner <name|id>", "owner (login, email, or name)")
+        .option("--partner <name|id>", "linked contact")
+        .option("--tag <name|id>", "tag; repeatable, AND-ed", collect, [])
+        .option("--description <text>", "description")
+        .option("--mimetype <type>", "MIME type (default: guessed from extension)")
+        .action(async (opts) => {
+        await run((g) => uploadCommand(opts, g), program);
+    });
     return program;
 }
 async function run(fn, program) {

package/dist/commands/activities.js

@@ -0,0 +1,239 @@
+import { OdooClient } from "../client.js";
+import { resolveConfig } from "../config.js";
+import { notFoundError, usageError } from "../errors.js";
+import { parseDate } from "../mutation.js";
+import { resolveReference } from "../model.js";
+import { printJson, verbose as logVerbose } from "../output.js";
+import { formatTable } from "../table.js";
+/**
+ * Scheduled activities (mail.activity) for crm.lead records.
+ *
+ * A `mail.activity` is the source of truth for a lead's next step. It carries
+ * a type (To-Do, Call, Meeting, Email, ...), a deadline, an assignee, and a
+ * short note. `action_done` marks it complete (the only reliable way to close
+ * an activity — writing state='done' directly does not work in Odoo).
+ */
+const CRM_LEAD_MODEL = "crm.lead";
+async function buildClient(globals) {
+    const config = await resolveConfig(globals);
+    if (!config.url || !config.db || !config.username || !config.apiKey) {
+        throw usageError("missing configuration", "run 'odoo auth login' or set ODOO_URL, ODOO_DB, ODOO_USERNAME, ODOO_API_KEY");
+    }
+    const { parseDurationMs } = await import("../duration.js");
+    const timeoutMs = parseDurationMs(globals.timeout);
+    return new OdooClient(config.url, config.db, config.username, config.apiKey, { timeoutMs, verbose: globals.verbose });
+}
+/** Resolve the ir.model id for a technical model name (e.g. "crm.lead"). */
+async function resolveResModelId(client, technicalName) {
+    const rows = (await client.executeKw("ir.model", "search_read", [[["model", "=", technicalName]]], { fields: ["id"], limit: 1 }));
+    if (rows.length === 0) {
+        throw notFoundError("model_not_found", `no ir.model for ${JSON.stringify(technicalName)}`);
+    }
+    return rows[0].id;
+}
+/**
+ * Schedule a new activity on a crm.lead record.
+ */
+export async function scheduleCommand(recordId, opts, globals) {
+    const id = Number.parseInt(recordId, 10);
+    if (Number.isNaN(id) || id <= 0) {
+        throw usageError(`invalid lead id: ${recordId}`, "provide a positive integer");
+    }
+    const client = await buildClient(globals);
+    // Verify the lead exists
+    const leads = (await client.executeKw(CRM_LEAD_MODEL, "search_read", [[["id", "=", id]]], { fields: ["id", "name"], limit: 1 }));
+    if (!leads || leads.length === 0) {
+        throw notFoundError("record_not_found", `crm.lead #${id} does not exist`, "check the lead id");
+    }
+    // Resolve the activity type by name or id
+    const activityType = await resolveReference(client, "mail.activity.type", opts.type, {
+        label: "activity type",
+    });
+    // Resolve the assignee (defaults to the authenticated user)
+    let assigneeId;
+    let assigneeName;
+    if (opts.assignee) {
+        const user = await resolveReference(client, "res.users", opts.assignee, {
+            label: "user",
+            searchFields: ["login", "email", "name"],
+        });
+        assigneeId = user.id;
+        assigneeName = user.name;
+    }
+    else {
+        // The authenticated user's own id is not directly exposed; resolve the
+        // current user via the uid returned by authenticate.
+        const uid = await client.authenticate();
+        const me = (await client.executeKw("res.users", "search_read", [[["id", "=", uid]]], { fields: ["id", "name"], limit: 1 }));
+        assigneeId = me[0]?.id ?? uid;
+        assigneeName = me[0]?.name ?? String(uid);
+    }
+    const resModelId = await resolveResModelId(client, CRM_LEAD_MODEL);
+    const deadline = parseDate(opts.deadline, "--deadline");
+    const values = {
+        res_model_id: resModelId,
+        res_id: id,
+        activity_type_id: activityType.id,
+        user_id: assigneeId,
+        date_deadline: deadline,
+        summary: opts.summary,
+        ...(opts.note ? { note: opts.note } : {}),
+    };
+    if (globals.verbose) {
+        logVerbose(`Scheduling activity on crm.lead #${id} (${leads[0].name})`, globals.verbose);
+        logVerbose(`Activity values: ${JSON.stringify(values, null, 2)}`, globals.verbose);
+    }
+    if (globals.dryRun) {
+        if (globals.json) {
+            printJson({
+                model: "mail.activity",
+                action: "create",
+                dry_run: true,
+                record: { model: CRM_LEAD_MODEL, id, name: leads[0].name },
+                values,
+                resolved: {
+                    activity_type_id: [activityType.id, activityType.name],
+                    user_id: [assigneeId, assigneeName],
+                },
+            });
+        }
+        else {
+            console.log(`[DRY RUN] Would schedule activity on crm.lead #${id} — ${leads[0].name}:`);
+            console.log(`  Type: ${activityType.name} (${activityType.id})`);
+            console.log(`  Assignee: ${assigneeName} (${assigneeId})`);
+            console.log(`  Deadline: ${deadline}`);
+            console.log(`  Summary: ${opts.summary}`);
+            if (opts.note)
+                console.log(`  Note: ${opts.note}`);
+        }
+        return;
+    }
+    const activityId = (await client.executeKw("mail.activity", "create", [
+        values,
+    ]));
+    if (globals.json) {
+        printJson({
+            model: "mail.activity",
+            action: "create",
+            dry_run: false,
+            id: activityId,
+            record: { model: CRM_LEAD_MODEL, id, name: leads[0].name },
+            resolved: {
+                activity_type_id: [activityType.id, activityType.name],
+                user_id: [assigneeId, assigneeName],
+            },
+        });
+    }
+    else {
+        console.log(`✓ Activity scheduled (ID: ${activityId})`);
+        console.log(`  Lead: crm.lead #${id} — ${leads[0].name}`);
+        console.log(`  Type: ${activityType.name} · Deadline: ${deadline} · Assignee: ${assigneeName}`);
+    }
+}
+/**
+ * Mark one or more activities as done via `action_done`.
+ */
+export async function activityDoneCommand(activityIds, globals) {
+    const ids = activityIds.map((raw) => {
+        const n = Number.parseInt(raw, 10);
+        if (Number.isNaN(n) || n <= 0) {
+            throw usageError(`invalid activity id: ${raw}`, "provide a positive integer");
+        }
+        return n;
+    });
+    const client = await buildClient(globals);
+    // Verify the activities exist
+    const rows = (await client.executeKw("mail.activity", "search_read", [[["id", "in", ids]]], { fields: ["id", "summary", "state"], limit: ids.length }));
+    const byId = new Map(rows.map((r) => [r.id, r]));
+    const missing = ids.filter((id) => !byId.has(id));
+    if (missing.length > 0) {
+        throw notFoundError("record_not_found", `no mail.activity record(s) with id(s): ${missing.join(", ")}`, "no activities were modified — aborts the whole batch when any id is missing");
+    }
+    if (globals.dryRun) {
+        if (globals.json) {
+            printJson({
+                model: "mail.activity",
+                action: "action_done",
+                dry_run: true,
+                ids,
+                activities: rows.map((r) => ({ id: r.id, summary: r.summary, state: r.state })),
+            });
+        }
+        else {
+            console.log(`[DRY RUN] Would mark ${ids.length} activity(ies) as done:`);
+            for (const r of rows) {
+                console.log(`  #${r.id} — ${r.summary} (${r.state})`);
+            }
+        }
+        return;
+    }
+    await client.executeKw("mail.activity", "action_done", [ids]);
+    if (globals.json) {
+        printJson({
+            model: "mail.activity",
+            action: "action_done",
+            dry_run: false,
+            done: ids,
+        });
+    }
+    else {
+        console.log(`✓ Marked ${ids.length} activity(ies) as done: ${ids.join(", ")}`);
+    }
+}
+/**
+ * List activities for a crm.lead record.
+ */
+export async function activitiesListCommand(recordId, opts, globals) {
+    const id = Number.parseInt(recordId, 10);
+    if (Number.isNaN(id) || id <= 0) {
+        throw usageError(`invalid lead id: ${recordId}`, "provide a positive integer");
+    }
+    const client = await buildClient(globals);
+    // Verify the lead exists
+    const leads = (await client.executeKw(CRM_LEAD_MODEL, "search_read", [[["id", "=", id]]], { fields: ["id", "name"], limit: 1 }));
+    if (!leads || leads.length === 0) {
+        throw notFoundError("record_not_found", `crm.lead #${id} does not exist`, "check the lead id");
+    }
+    const resModelId = await resolveResModelId(client, CRM_LEAD_MODEL);
+    const domain = [
+        ["res_model_id", "=", resModelId],
+        ["res_id", "=", id],
+    ];
+    if (opts.open) {
+        domain.push(["state", "in", ["pending", "planned", "a_review"]]);
+    }
+    const limit = opts.limit ? Number.parseInt(opts.limit, 10) : 50;
+    const activities = (await client.executeKw("mail.activity", "search_read", [domain], {
+        fields: [
+            "id",
+            "activity_type_id",
+            "date_deadline",
+            "summary",
+            "note",
+            "state",
+            "user_id",
+        ],
+        limit,
+        order: "date_deadline asc",
+    }));
+    if (globals.json) {
+        printJson({
+            model: "mail.activity",
+            record: { model: CRM_LEAD_MODEL, id, name: leads[0].name },
+            count: activities.length,
+            activities,
+        });
+        return;
+    }
+    console.log(`Activities for crm.lead #${id}: ${leads[0].name}`);
+    console.log(`Found ${activities.length} activities\n`);
+    const rows = activities.map((a) => [
+        a.id.toString(),
+        a.state,
+        a.activity_type_id ? a.activity_type_id[1] : "",
+        a.date_deadline ? String(a.date_deadline) : "",
+        a.user_id ? a.user_id[1] : "",
+        a.summary,
+    ]);
+    console.log(formatTable(["ID", "State", "Type", "Deadline", "Assignee", "Summary"], rows, !globals.noColor));
+}

package/dist/commands/crm.js

@@ -134,7 +134,24 @@ const crmLeadsMutation = {
             field: "description",
             help: "Notes",
         },
+        {
+            flags: "--lead-type <type>",
+            option: "leadType",
+            field: "x_studio_lead_type",
+            help: "Lead type: Inbound|Outbound|Not sure (default: Inbound)",
+            parse: (raw, flagName) => {
+                const v = raw.trim();
+                const valid = ["Inbound", "Outbound", "Not sure"];
+                if (!valid.includes(v)) {
+                    throw usageError(`invalid ${flagName} ${JSON.stringify(raw)}`, `expected one of: ${valid.join(", ")}`);
+                }
+                return v;
+            },
+        },
     ],
+    createDefaultValues: {
+        x_studio_lead_type: "Inbound",
+    },
 };
 export const crmLeads = {
     model: "crm.lead",

package/dist/commands/documents.js

@@ -0,0 +1,402 @@
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { basename, extname, resolve } from "node:path";
+import { usageError } from "../errors.js";
+import { ModelFields, resolveReference } from "../model.js";
+import { createCommand, deleteCommand, updateCommand, } from "../mutation.js";
+import { colorEnabled, printJson } from "../output.js";
+import { authenticatedClient, listCommand, showCommand, } from "../resource.js";
+import { formatTable, humanCell } from "../table.js";
+const FOLDER_DOMAIN = [["type", "=", "folder"]];
+/** documents.document mutation flags (folders + binary files share the model). */
+const documentsMutation = {
+    flags: [
+        {
+            flags: "--name <name>",
+            option: "name",
+            field: "name",
+            help: "Document or folder name",
+            requiredOnCreate: true,
+        },
+        {
+            flags: "--folder <name|id>",
+            option: "folder",
+            field: "folder_id",
+            help: "Parent folder",
+            reference: { model: "documents.document", label: "folder" },
+        },
+        {
+            flags: "--owner <name|id>",
+            option: "owner",
+            field: "owner_id",
+            help: "Owner (login, email, or name)",
+            reference: {
+                model: "res.users",
+                label: "user",
+                searchFields: ["login", "email", "name"],
+            },
+        },
+        {
+            flags: "--partner <name|id>",
+            option: "partner",
+            field: "partner_id",
+            help: "Related partner",
+            reference: { model: "res.partner", label: "partner" },
+        },
+        {
+            flags: "--tag <name|id>",
+            option: "tag",
+            field: "tag_ids",
+            help: "Tag; repeatable, replaces all tags",
+            multi: true,
+            reference: { model: "documents.tag", label: "tag" },
+        },
+        {
+            flags: "--description <text>",
+            option: "description",
+            field: "description",
+            help: "Description",
+        },
+        {
+            flags: "--link <url>",
+            option: "link",
+            field: "url",
+            help: "External URL (creates a link document)",
+        },
+        {
+            flags: "--folder-type <folder>",
+            option: "folderType",
+            field: "type",
+            help: "Create a folder instead of a document (pass --folder-type folder)",
+            parse: (raw, flagName) => {
+                if (raw !== "folder") {
+                    throw usageError(`invalid ${flagName} value ${JSON.stringify(raw)}`, "expected: folder");
+                }
+                return "folder";
+            },
+        },
+    ],
+};
+export const documentsDocuments = {
+    model: "documents.document",
+    showCommand: "odoo documents records show",
+    defaultListFields: [
+        "id",
+        "name",
+        "type",
+        "folder_id",
+        "mimetype",
+        "file_size",
+        "owner_id",
+        "create_date",
+    ],
+    showExtraFields: [
+        "partner_id",
+        "tag_ids",
+        "description",
+        "url",
+        "access_internal",
+        "access_via_link",
+        "access_url",
+        "is_editable_attachment",
+        "handler",
+        "active",
+        "shortcut_document_id",
+        "write_date",
+    ],
+    resolutionHints: {
+        folder_id: "--folder",
+        owner_id: "--owner",
+        partner_id: "--partner",
+        tag_ids: "--tag",
+    },
+    priorityLabels: {},
+    pinnedDomain: [["type", "!=", "folder"]],
+    references: {
+        assignee: {
+            model: "res.users",
+            label: "user",
+            field: "owner_id",
+            searchFields: ["login", "email", "name"],
+        },
+        tag: { model: "documents.tag", label: "tag", field: "tag_ids" },
+    },
+    mutation: documentsMutation,
+    extraFilters: async (opts, client) => {
+        const o = opts;
+        const clauses = [];
+        if (o.folder !== undefined) {
+            clauses.push(["folder_id", "=", await resolveFolderId(client, o.folder)]);
+        }
+        if (o.type === "folder") {
+            clauses.push(["type", "=", "folder"]);
+        }
+        else if (o.type === "binary") {
+            clauses.push(["type", "=", "binary"]);
+        }
+        else if (o.type === "url") {
+            clauses.push(["type", "=", "url"]);
+        }
+        else if (o.type === "all") {
+            // no extra clause — but pinnedDomain excludes folders, so drop it
+            // (handled by caller clearing pinnedDomain)
+        }
+        return clauses;
+    },
+};
+/**
+ * List folders only (type = 'folder'). Same list engine, pinned domain
+ * flipped to folders-only.
+ */
+export const documentsFolders = {
+    ...documentsDocuments,
+    showCommand: "odoo documents folders show",
+    pinnedDomain: FOLDER_DOMAIN,
+};
+export const documentsAll = {
+    ...documentsDocuments,
+    pinnedDomain: [],
+};
+export function documentsListCommand(opts, globals) {
+    const config = opts.type === "all"
+        ? documentsAll
+        : opts.type === "folder"
+            ? documentsFolders
+            : documentsDocuments;
+    return listCommand(config, opts, globals);
+}
+export function foldersListCommand(opts, globals) {
+    return listCommand(documentsFolders, opts, globals);
+}
+export function documentsShowCommand(idArg, opts, globals) {
+    return showCommand(documentsAll, idArg, opts, globals);
+}
+export function documentsCreateCommand(opts, globals) {
+    const config = opts.folderType === "folder" ? documentsAll : documentsDocuments;
+    return createCommand(config, opts, globals);
+}
+export function documentsUpdateCommand(idArgs, opts, globals) {
+    return updateCommand(documentsAll, idArgs, opts, globals);
+}
+export function documentsDeleteCommand(idArgs, globals) {
+    return deleteCommand(documentsAll, idArgs, globals);
+}
+export async function treeCommand(opts, globals) {
+    const client = await authenticatedClient(globals);
+    await ModelFields.load(client, "documents.document"); // module-installed check
+    const maxDepth = Number(opts.depth);
+    if (!Number.isInteger(maxDepth) || maxDepth < 1) {
+        throw usageError(`invalid --depth value ${JSON.stringify(opts.depth)}`, "expected a positive integer");
+    }
+    // Root resolution: --folder given → that folder as root; otherwise roots.
+    let rootId = false;
+    let rootName = "Documents";
+    if (opts.folder !== undefined) {
+        rootId = await resolveFolderId(client, opts.folder);
+        const rows = (await client.executeKw("documents.document", "read", [
+            [rootId],
+            ["name"],
+        ]));
+        rootName = rows[0]?.name ?? rootName;
+    }
+    const [folders, docs] = await Promise.all([
+        client.executeKw("documents.document", "search_read", [FOLDER_DOMAIN], { fields: ["id", "name", "folder_id"], limit: 5000 }),
+        opts.count
+            ? client.executeKw("documents.document", "search_read", [[["type", "!=", "folder"]]], { fields: ["id", "folder_id"], limit: 50000 })
+            : Promise.resolve([]),
+    ]);
+    const countByFolder = new Map();
+    for (const d of docs) {
+        const fid = Array.isArray(d.folder_id) ? d.folder_id[0] : false;
+        if (fid !== false) {
+            countByFolder.set(fid, (countByFolder.get(fid) ?? 0) + 1);
+        }
+    }
+    const nodes = new Map();
+    for (const f of folders) {
+        nodes.set(f.id, {
+            id: f.id,
+            name: f.name,
+            parentId: Array.isArray(f.folder_id) ? f.folder_id[0] : false,
+            documentCount: countByFolder.get(f.id) ?? 0,
+            children: [],
+        });
+    }
+    for (const node of nodes.values()) {
+        if (node.parentId !== false) {
+            const parent = nodes.get(node.parentId);
+            if (parent)
+                parent.children.push(node);
+        }
+    }
+    // Root set: explicit folder, or all folders without a parent in the map.
+    const roots = [];
+    if (rootId !== false) {
+        const root = nodes.get(rootId);
+        if (root)
+            roots.push(root);
+    }
+    else {
+        for (const node of nodes.values()) {
+            if (node.parentId === false || !nodes.has(node.parentId)) {
+                roots.push(node);
+            }
+        }
+    }
+    roots.sort((a, b) => a.name.localeCompare(b.name));
+    if (globals.json) {
+        const toJson = (n) => ({
+            id: n.id,
+            name: n.name,
+            document_count: n.documentCount,
+            children: n.children
+                .sort((a, b) => a.name.localeCompare(b.name))
+                .map(toJson),
+        });
+        printJson({ root: rootName, tree: roots.map(toJson) });
+        return;
+    }
+    const lines = [];
+    const renderRec = (node, prefix, depth) => {
+        const countSuffix = opts.count ? ` (${node.documentCount})` : "";
+        lines.push(`${prefix}${node.name}${countSuffix}`);
+        if (depth >= maxDepth)
+            return;
+        const children = [...node.children].sort((a, b) => a.name.localeCompare(b.name));
+        for (let i = 0; i < children.length; i++) {
+            const last = i === children.length - 1;
+            renderRec(children[i], prefix + (last ? "└── " : "├── "), depth + 1);
+        }
+    };
+    for (const root of roots) {
+        renderRec(root, "", 1);
+    }
+    process.stdout.write(lines.join("\n") + "\n");
+}
+// ---------------------------------------------------------------------------
+// upload — local file → binary document
+// ---------------------------------------------------------------------------
+const MIME_BY_EXT = {
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".csv": "text/csv",
+    ".json": "application/json",
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ".doc": "application/msword",
+    ".xls": "application/vnd.ms-excel",
+    ".ppt": "application/vnd.ms-powerpoint",
+    ".zip": "application/zip",
+    ".html": "text/html",
+    ".xml": "application/xml",
+};
+export async function uploadCommand(opts, globals) {
+    const client = await authenticatedClient(globals);
+    const fieldsMeta = await ModelFields.load(client, "documents.document");
+    const filePath = resolve(opts.file);
+    let fileStat;
+    try {
+        fileStat = await stat(filePath);
+    }
+    catch {
+        throw usageError(`file not found: ${opts.file}`);
+    }
+    if (!fileStat.isFile()) {
+        throw usageError(`not a regular file: ${opts.file}`);
+    }
+    const name = opts.name ?? basename(filePath);
+    const mimetype = opts.mimetype ??
+        MIME_BY_EXT[extname(filePath).toLowerCase()] ??
+        "application/octet-stream";
+    // Read + base64
+    const buffer = await readFile(filePath);
+    const datas = buffer.toString("base64");
+    const checksum = createHash("sha1").update(buffer).digest("hex");
+    const values = {
+        name,
+        mimetype,
+        file_size: fileStat.size,
+        checksum,
+        datas,
+    };
+    if (opts.folder !== undefined) {
+        values.folder_id = await resolveFolderId(client, opts.folder);
+    }
+    if (opts.owner !== undefined) {
+        const user = await resolveReference(client, "res.users", opts.owner, {
+            label: "user",
+            searchFields: ["login", "email", "name"],
+        });
+        values.owner_id = user.id;
+    }
+    if (opts.partner !== undefined) {
+        const partner = await resolveReference(client, "res.partner", opts.partner, { label: "partner" });
+        values.partner_id = partner.id;
+    }
+    if (opts.tag && opts.tag.length > 0) {
+        const ids = [];
+        for (const t of opts.tag) {
+            const tag = await resolveReference(client, "documents.tag", t, {
+                label: "tag",
+            });
+            ids.push(tag.id);
+        }
+        values.tag_ids = [[6, 0, ids]];
+    }
+    if (opts.description !== undefined) {
+        values.description = opts.description;
+    }
+    if (globals.dryRun) {
+        const preview = { ...values, datas: `<${buffer.length} bytes base64>` };
+        if (globals.json) {
+            printJson({
+                model: "documents.document",
+                action: "upload",
+                dry_run: true,
+                values: preview,
+            });
+            return;
+        }
+        process.stdout.write(`Would upload documents.document:\n` +
+            Object.entries(preview)
+                .map(([k, v]) => `  ${k}: ${JSON.stringify(v)}`)
+                .join("\n") +
+            "\n");
+        return;
+    }
+    const id = (await client.executeKw("documents.document", "create", [
+        values,
+    ]));
+    if (globals.json) {
+        printJson({
+            model: "documents.document",
+            action: "upload",
+            dry_run: false,
+            id,
+            name,
+            mimetype,
+            file_size: fileStat.size,
+        });
+        return;
+    }
+    const color = colorEnabled(false) && process.stdout.isTTY === true;
+    const line = `Uploaded documents.document ${id} (${name})`;
+    process.stdout.write((color ? `\x1b[32m${line}\x1b[0m` : line) + "\n");
+}
+/** Resolve a folder by name or id (must be type=folder). */
+async function resolveFolderId(client, input) {
+    const resolved = await resolveReference(client, "documents.document", input, {
+        label: "folder",
+        domain: FOLDER_DOMAIN,
+    });
+    return resolved.id;
+}
+export { formatTable, humanCell };

package/dist/commands/notes.js

@@ -3,12 +3,27 @@ import { resolveConfig } from "../config.js";
 import { notFoundError, usageError } from "../errors.js";
 import { printJson, verbose as logVerbose } from "../output.js";
 import { formatTable } from "../table.js";
-export async function addNoteCommand(ticketId, opts, globals) {
-    const id = Number.parseInt(ticketId, 10);
-    if (Number.isNaN(id) || id <= 0) {
-        throw usageError(`invalid ticket id: ${ticketId}`, "provide a positive integer");
+const THREAD_MODELS = {
+    "helpdesk.ticket": { model: "helpdesk.ticket", label: "ticket" },
+    "crm.lead": { model: "crm.lead", label: "lead" },
+};
+function threadModel(model) {
+    const spec = THREAD_MODELS[model];
+    if (!spec) {
+        throw usageError(`unsupported thread model ${JSON.stringify(model)}`, `expected one of: ${Object.keys(THREAD_MODELS).join(", ")}`);
+    }
+    return spec;
+}
+async function buildClient(globals) {
+    const config = await resolveConfig(globals);
+    if (!config.url || !config.db || !config.username || !config.apiKey) {
+        throw usageError("missing configuration", "run 'odoo auth login' or set ODOO_URL, ODOO_DB, ODOO_USERNAME, ODOO_API_KEY");
     }
-    // Read body from file if specified
+    const { parseDurationMs } = await import("../duration.js");
+    const timeoutMs = parseDurationMs(globals.timeout);
+    return new OdooClient(config.url, config.db, config.username, config.apiKey, { timeoutMs, verbose: globals.verbose });
+}
+async function readBody(opts) {
     let body = opts.body;
     if (opts.bodyFile) {
         const fs = await import("node:fs/promises");
@@ -22,39 +37,45 @@ export async function addNoteCommand(ticketId, opts, globals) {
     if (!body || body.trim().length === 0) {
         throw usageError("note body cannot be empty", "provide --body or --body-file");
     }
-    const config = await resolveConfig(globals);
-    if (!config.url || !config.db || !config.username || !config.apiKey) {
-        throw usageError("missing configuration", "run 'odoo auth login' or set ODOO_URL, ODOO_DB, ODOO_USERNAME, ODOO_API_KEY");
+    return body;
+}
+/**
+ * Add an internal Log Note to a mail-thread record (ticket or lead).
+ */
+export async function addNoteCommand(recordId, opts, globals, model) {
+    const spec = threadModel(model);
+    const id = Number.parseInt(recordId, 10);
+    if (Number.isNaN(id) || id <= 0) {
+        throw usageError(`invalid ${spec.label} id: ${recordId}`, "provide a positive integer");
     }
-    const { parseDurationMs } = await import("../duration.js");
-    const timeoutMs = parseDurationMs(globals.timeout);
-    const client = new OdooClient(config.url, config.db, config.username, config.apiKey, { timeoutMs, verbose: globals.verbose });
-    // Verify ticket exists
-    const tickets = (await client.executeKw("helpdesk.ticket", "search_read", [[["id", "=", id]]], { fields: ["id", "name"], limit: 1 }));
-    if (!tickets || tickets.length === 0) {
-        throw notFoundError("ticket_not_found", `helpdesk ticket #${id} does not exist`, "check the ticket id");
+    const body = await readBody(opts);
+    const client = await buildClient(globals);
+    // Verify the record exists
+    const rows = (await client.executeKw(spec.model, "search_read", [[["id", "=", id]]], { fields: ["id", "name"], limit: 1 }));
+    if (!rows || rows.length === 0) {
+        throw notFoundError("record_not_found", `${spec.model} #${id} does not exist`, `check the ${spec.label} id`);
     }
     // Create internal Log Note
     // CRITICAL: These parameters ensure the note is INTERNAL ONLY
     // - subtype_id=2: "Note" subtype (internal, not sent to customer)
     // - message_type="comment": Internal comment (not email)
-    // - author_id: Use the authenticated user's partner_id
     const noteParams = {
-        model: "helpdesk.ticket",
+        model: spec.model,
         res_id: id,
         body: body,
         message_type: "comment",
         subtype_id: 2, // Note subtype = internal only, NEVER sends email
     };
     if (globals.verbose) {
-        logVerbose(`Creating internal note for ticket #${id} (${tickets[0].name})`, globals.verbose);
+        logVerbose(`Creating internal note for ${spec.model} #${id} (${rows[0].name})`, globals.verbose);
         logVerbose(`Note parameters: ${JSON.stringify(noteParams, null, 2)}`, globals.verbose);
     }
     if (globals.dryRun) {
         const result = {
             dry_run: true,
-            ticket_id: id,
-            ticket_name: tickets[0].name,
+            model: spec.model,
+            record_id: id,
+            record_name: rows[0].name,
             note_type: "internal_log_note",
             will_send_email: false,
             body_preview: body.substring(0, 100) + (body.length > 100 ? "..." : ""),
@@ -65,7 +86,7 @@ export async function addNoteCommand(ticketId, opts, globals) {
         }
         else {
             console.log(`[DRY RUN] Would create internal Log Note:`);
-            console.log(`  Ticket: #${id} — ${tickets[0].name}`);
+            console.log(`  Record: ${spec.model} #${id} — ${rows[0].name}`);
             console.log(`  Type: Internal note (never sent to customer)`);
             console.log(`  Body length: ${body.length} characters`);
             console.log(`  Body preview: ${result.body_preview}`);
@@ -77,8 +98,9 @@ export async function addNoteCommand(ticketId, opts, globals) {
     ]));
     const result = {
         note_id: noteId,
-        ticket_id: id,
-        ticket_name: tickets[0].name,
+        model: spec.model,
+        record_id: id,
+        record_name: rows[0].name,
         note_type: "internal_log_note",
         email_sent: false,
     };
@@ -87,37 +109,31 @@ export async function addNoteCommand(ticketId, opts, globals) {
     }
     else {
         console.log(`✓ Internal Log Note created (ID: ${noteId})`);
-        console.log(`  Ticket: #${id} — ${tickets[0].name}`);
+        console.log(`  Record: ${spec.model} #${id} — ${rows[0].name}`);
         console.log(`  Type: Internal note (not sent to customer)`);
     }
 }
 /**
- * List messages for a helpdesk ticket.
+ * List messages for a mail-thread record (emails, comments, notes).
  *
- * Fetches all messages (emails, comments, notes) associated with a ticket.
- * Useful for analyzing ticket history and determining if customer is waiting
- * for a response.
+ * Fetches all messages associated with the record. Useful for analyzing
+ * history and determining if the customer is waiting for a response.
  */
-export async function listMessagesCommand(ticketId, opts, globals) {
-    const id = Number.parseInt(ticketId, 10);
+export async function listMessagesCommand(recordId, opts, globals, model) {
+    const spec = threadModel(model);
+    const id = Number.parseInt(recordId, 10);
     if (Number.isNaN(id) || id <= 0) {
-        throw usageError(`invalid ticket id: ${ticketId}`, "provide a positive integer");
+        throw usageError(`invalid ${spec.label} id: ${recordId}`, "provide a positive integer");
     }
-    const config = await resolveConfig(globals);
-    if (!config.url || !config.db || !config.username || !config.apiKey) {
-        throw usageError("missing configuration", "run 'odoo auth login' or set ODOO_URL, ODOO_DB, ODOO_USERNAME, ODOO_API_KEY");
-    }
-    const { parseDurationMs } = await import("../duration.js");
-    const timeoutMs = parseDurationMs(globals.timeout);
-    const client = new OdooClient(config.url, config.db, config.username, config.apiKey, { timeoutMs, verbose: globals.verbose });
-    // Verify ticket exists
-    const tickets = (await client.executeKw("helpdesk.ticket", "search_read", [[["id", "=", id]]], { fields: ["id", "name"], limit: 1 }));
-    if (!tickets || tickets.length === 0) {
-        throw notFoundError("ticket_not_found", `helpdesk ticket #${id} does not exist`, "check the ticket id");
+    const client = await buildClient(globals);
+    // Verify the record exists
+    const rows = (await client.executeKw(spec.model, "search_read", [[["id", "=", id]]], { fields: ["id", "name"], limit: 1 }));
+    if (!rows || rows.length === 0) {
+        throw notFoundError("record_not_found", `${spec.model} #${id} does not exist`, `check the ${spec.label} id`);
     }
     // Build domain for messages
     const domain = [
-        ["model", "=", "helpdesk.ticket"],
+        ["model", "=", spec.model],
         ["res_id", "=", id],
     ];
     // Add optional filters
@@ -141,7 +157,7 @@ export async function listMessagesCommand(ticketId, opts, globals) {
     }
     const limit = opts.limit ? Number.parseInt(opts.limit, 10) : 50;
     if (globals.verbose) {
-        logVerbose(`Fetching messages for ticket #${id}`, globals.verbose);
+        logVerbose(`Fetching messages for ${spec.model} #${id}`, globals.verbose);
         logVerbose(`Domain: ${JSON.stringify(domain)}`, globals.verbose);
     }
     const messages = (await client.executeKw("mail.message", "search_read", [domain], {
@@ -160,16 +176,17 @@ export async function listMessagesCommand(ticketId, opts, globals) {
     }));
     if (globals.json) {
         printJson({
-            ticket_id: id,
-            ticket_name: tickets[0].name,
+            model: spec.model,
+            record_id: id,
+            record_name: rows[0].name,
             message_count: messages.length,
             messages,
         });
     }
     else {
-        console.log(`Messages for ticket #${id}: ${tickets[0].name}`);
+        console.log(`Messages for ${spec.model} #${id}: ${rows[0].name}`);
         console.log(`Found ${messages.length} messages\n`);
-        const rows = messages.map((msg) => {
+        const rowsOut = messages.map((msg) => {
             const author = msg.author_id ? msg.author_id[1] : msg.email_from || "System";
             const subtype = msg.subtype_id ? msg.subtype_id[1] : "";
             const bodyPreview = msg.body
@@ -186,6 +203,6 @@ export async function listMessagesCommand(ticketId, opts, globals) {
                 bodyPreview + (msg.body.length > 60 ? "..." : ""),
             ];
         });
-        console.log(formatTable(["ID", "Date", "Type", "Subtype", "Author", "Preview"], rows, !globals.noColor));
+        console.log(formatTable(["ID", "Date", "Type", "Subtype", "Author", "Preview"], rowsOut, !globals.noColor));
     }
 }

package/dist/mutation.js

@@ -40,13 +40,10 @@ export async function buildValues(client, config, spec, opts, mode, globals) {
     const resolvedByOption = {};
     const claim = (field, source) => {
         const prev = sourceOf[field];
-        if (prev === undefined) {
+        if (prev === undefined || prev === "default") {
             sourceOf[field] = source;
             return;
         }
-        if (prev === "pinned") {
-            throw usageError(`field "${field}" is pinned by this collection and cannot be overridden`, `remove --${kebab(/* context only */ "")}: the ${config.model.split(".")[0]} surface fixes ${field}`);
-        }
         throw usageError(`field "${field}" given by both ${prev} and ${source}`, "pass each field exactly once (SPEC §4.2)");
     };
     // 1. Pinned create values first (e.g. type=lead). They cannot be overridden
@@ -56,6 +53,13 @@ export async function buildValues(client, config, spec, opts, mode, globals) {
             values[k] = v;
             sourceOf[k] = "pinned";
         }
+        // 1b. Default create values — can be overridden by explicit flags/--set/--values.
+        for (const [k, v] of Object.entries(spec.createDefaultValues ?? {})) {
+            if (values[k] === undefined) {
+                values[k] = v;
+                sourceOf[k] = "default";
+            }
+        }
     }
     // 2. Exclusive groups (--partner vs --customer-*/--customer-name, §6.3).
     for (const group of spec.exclusiveGroups ?? []) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bergetai/odoo-cli",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "Agent-first CLI for the Odoo External API",
   "publishConfig": {
     "access": "public"