@tuanhv/op-cli 0.1.0 → 0.2.0

package/LICENSE

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

package/NOTICE

@@ -11,5 +11,5 @@ OpenProject in the documentation and command output describe
 interoperability with the OpenProject REST API only; they are nominative
 references to that product, not claims of association.
 
-op-cli is released under the MIT license; see the "license" field of
-package.json.
+op-cli is released under the MIT license; see the LICENSE file. The
+"license" field of package.json carries the same grant.

package/README.md

@@ -7,9 +7,9 @@
 > GmbH; this tool only speaks the REST API of the OpenProject application you
 > already run. See the NOTICE file for the full statement.
 >
-> **Early release.** This is version 0.1.0 of a young tool. The command
-> surface may still change between releases; pin your version if that
-> matters to you.
+> **Early release.** This is an early 0.x release of a young tool. The
+> command surface may still change between releases; pin your version
+> if that matters to you.
 
 A resolving CLI for OpenProject: every flag accepts a human name or an id,
 and the tool turns names into ids itself. Errors carry stable `[CODE]`
@@ -22,6 +22,8 @@ markers so both humans and agents can react to them programmatically.
 
 ## From install to first useful command
 
+The npm package is [@tuanhv/op-cli](https://www.npmjs.com/package/@tuanhv/op-cli):
+
 ```sh
 npm install -g @tuanhv/op-cli
 op-cli auth login        # prompts for URL and API key; needs an interactive terminal
@@ -37,10 +39,14 @@ points beyond the quickstart:
 
 ```sh
 op-cli wp create "Fix login bug" --type Bug --priority High
+op-cli wp list --search login          # server-side subject search
 op-cli time log 42 --hours 1h30m --activity Development
+op-cli time report --from 2026-08-01 --to 2026-08-31   # closed period
 op-cli project member add web alice Manager   # join members so assignment works
 op-cli project list --search web
+op-cli wp move 42 archive              # move a work package to another project
 op-cli doctor            # diagnose connectivity, credentials, versions
+op-cli update            # self-update; prints the right command for Volta/Homebrew
 ```
 
 ## Things worth knowing
@@ -52,6 +58,13 @@ op-cli doctor            # diagnose connectivity, credentials, versions
   default project, scopes `wp list`, `wp count`, `time list`, and
   `time report` to that project and its subprojects. Without one, those
   four commands report instance-wide.
+- **Finding things needs no id.** `wp list --search <text>` matches
+  subjects server-side, `--created-after` / `--updated-after` bound by
+  date, and `time list` / `time report` take `--from` and an inclusive
+  `--to`. Every name flag also accepts the human name or the id.
+- **Tables respect the terminal.** Read from a terminal, a table is
+  bounded to its width and long cells are cut with an ellipsis; `--json`
+  output is never truncated.
 - **Deletion is guarded.** Deleting a project is irreversible: `wp delete`,
   `time delete`, and `project delete` all require an explicit `--yes`.
   `user delete` is not offered at all; there is no workaround by design.
@@ -65,8 +78,10 @@ op-cli doctor            # diagnose connectivity, credentials, versions
   when `OPENPROJECT_URL` / `OPENPROJECT_API_KEY` are exported; without the
   flag the environment wins over the active profile. A command served by the
   environment reports itself as the profile `env`.
-- **`project copy` copies properties only** (description, visibility, and
-  parent). It does not copy work packages, members, or wiki pages.
+- **Update notices are interactive-only.** Commands run from a terminal
+  check npm for a newer release at most once a day and print one stderr
+  line; scripted use (stderr not a TTY) never checks, `--version` stays
+  offline, and `OP_CLI_NO_UPDATE_CHECK=1` disables the check entirely.
 - **No escape hatch by design.** If a command is missing there is no raw
   HTTP passthrough; report the gap instead of working around the tool.
 
@@ -94,7 +109,8 @@ mappings; do not build on it.
 npm run build   # compile src/ to dist/
 npm test        # unit tests over fixtures from a real instance
 npm run lint
-scripts/smoke.sh  # REQUIRED gate before publishing
+scripts/smoke.sh              # REQUIRED gate before publishing
+npm publish --access public   # scoped package; public is not the default
 ```
 
 `scripts/smoke.sh` exercises a real create, update, time log, and delete
@@ -103,6 +119,11 @@ lifecycle against a scratch project on a live instance configured through
 broken step. There are no automated integration tests by design; this
 script is the regression net for real write paths before every publish.
 
-## License
+Releases after the first can ship from CI: once the package exists and its
+npm Trusted Publishers entry points at `.github/workflows/release.yml`,
+pushing a `v*` tag has GitHub Actions publish with a short-lived OIDC token
+and provenance; no npm token is stored anywhere.
 
-MIT. See the NOTICE file for the trademark statement.
+## License
+MIT; see the LICENSE file. See the NOTICE file for the trademark
+statement.

package/dist/bin.js

@@ -1,6 +1,24 @@
 #!/usr/bin/env node
 import { createNodeIo } from "./io/node-io.js";
 import { run } from "./run.js";
+/** 128 + 13: the exit status a shell reports for a process killed by SIGPIPE. */
+const EXIT_SIGPIPE = 141;
+/**
+ * Node ignores SIGPIPE, so writing after a pipe consumer is gone (`op-cli
+ * wp list | head`) surfaces as an EPIPE stream error. Without a listener
+ * that error escalates to an uncaught exception with a stack trace; exit
+ * quietly instead, and let every other write error keep crashing as before.
+ */
+function exitOnBrokenPipe(stream) {
+    stream.once("error", (error) => {
+        if (error.code === "EPIPE") {
+            process.exit(EXIT_SIGPIPE);
+        }
+        throw error;
+    });
+}
+exitOnBrokenPipe(process.stdout);
+exitOnBrokenPipe(process.stderr);
 const result = await run(process.argv.slice(2), process.env, createNodeIo());
 process.stdout.write(result.stdout);
 process.stderr.write(result.stderr);

package/dist/commands/doctor.js

@@ -25,9 +25,12 @@ function errorCodeOf(error) {
 }
 function versionSummary(info) {
     if (info.apiVersion === null && info.coreVersion === null) {
-        return "api unknown, core unknown (stock instances may omit this)";
+        return "reported neither version; the root document is optional, so core 13+ may still be running";
     }
-    return `api ${info.apiVersion ?? "unknown"}, core ${info.coreVersion ?? "unknown"}`;
+    if (info.apiVersion === null) {
+        return `core ${info.coreVersion ?? "unknown"}; api version not reported, core 13+ is what the check reads`;
+    }
+    return `api ${info.apiVersion}, core ${info.coreVersion ?? "unknown"}`;
 }
 export function registerDoctorCommand(parent, runtime) {
     parent

package/dist/commands/meta.js

@@ -1,18 +1,23 @@
 import { clearStoredMetadata, customFieldAllowedNames, loadProjectVocabulary, loadStoredMetadata, readStoredMetadata, refreshStoredMetadata, } from "../context/metadata.js";
-import { parseOptionalId } from "../context/profile.js";
+import { parseProjectOverride } from "../context/profile.js";
 import { defineLookupCommand, } from "../core/define.js";
 import { renderTable } from "../output/table.js";
 function star(value) {
     return value === true ? "*" : "";
 }
 const projectOption = {
-    flag: "--project <id>",
+    flag: "--project <name-or-id>",
     description: "override the profile default project",
 };
+const profileOption = {
+    flag: "--profile <name>",
+    description: "use this profile for this command only",
+};
 const typeLookup = {
     name: "types",
     description: "List the work package types of the instance",
     select: (metadata) => metadata.types,
+    options: [profileOption],
     columns: [
         { title: "ID", cell: (entry) => String(entry.id) },
         { title: "NAME", cell: (entry) => entry.name },
@@ -23,6 +28,7 @@ const statusLookup = {
     name: "statuses",
     description: "List the work package statuses of the instance",
     select: (metadata) => metadata.statuses,
+    options: [profileOption],
     columns: [
         { title: "ID", cell: (entry) => String(entry.id) },
         { title: "NAME", cell: (entry) => entry.name },
@@ -46,6 +52,7 @@ const priorityLookup = {
     name: "priorities",
     description: "List the work package priorities of the instance",
     select: (metadata) => metadata.priorities,
+    options: [profileOption],
     columns: [
         { title: "ID", cell: (entry) => String(entry.id) },
         { title: "NAME", cell: (entry) => entry.name },
@@ -56,7 +63,7 @@ const memberLookup = {
     name: "members",
     description: "List the members of the active project",
     select: (vocabulary) => vocabulary.members,
-    options: [projectOption],
+    options: [profileOption, projectOption],
     columns: [
         { title: "ID", cell: (entry) => String(entry.user_id) },
         { title: "NAME", cell: (entry) => entry.name },
@@ -71,7 +78,7 @@ const versionLookup = {
     name: "versions",
     description: "List the versions of the active project",
     select: (vocabulary) => vocabulary.versions,
-    options: [projectOption],
+    options: [profileOption, projectOption],
     columns: [
         { title: "ID", cell: (entry) => String(entry.id) },
         { title: "NAME", cell: (entry) => entry.name },
@@ -82,7 +89,7 @@ const categoryLookup = {
     name: "categories",
     description: "List the categories of the active project",
     select: (vocabulary) => vocabulary.categories,
-    options: [projectOption],
+    options: [profileOption, projectOption],
     columns: [
         { title: "ID", cell: (entry) => String(entry.id) },
         { title: "NAME", cell: (entry) => entry.name },
@@ -122,7 +129,7 @@ const fieldLookup = {
     name: "fields",
     description: "List the custom fields of the active project",
     select: uniqueFields,
-    options: [projectOption],
+    options: [profileOption, projectOption],
     columns: [
         { title: "ID", cell: (entry) => String(entry.id) },
         { title: "NAME", cell: (entry) => entry.name },
@@ -138,7 +145,7 @@ const activityLookup = {
     name: "activities",
     description: "List the time entry activities of the active project",
     select: (vocabulary) => vocabulary.activities,
-    options: [projectOption],
+    options: [profileOption, projectOption],
     columns: [
         { title: "ID", cell: (entry) => String(entry.id) },
         { title: "NAME", cell: (entry) => entry.name },
@@ -149,10 +156,11 @@ function registerShow(parent, runtime) {
     const command = parent
         .command("show")
         .description("Show the stored metadata of the active profile")
+        .option("--profile <name>", "use this profile for this command only")
         .option("--json", "emit a JSON object");
     command.action(async (options) => {
         runtime.setJsonMode(options.json === true);
-        const profile = await runtime.resolve();
+        const profile = await runtime.resolve({ profile: options.profile });
         const stored = await readStoredMetadata(runtime.env, profile);
         if (stored === undefined) {
             runtime.write(options.json === true
@@ -186,10 +194,11 @@ function registerRefresh(parent, runtime) {
     const command = parent
         .command("refresh")
         .description("Re-fetch the stored metadata and report what changed")
+        .option("--profile <name>", "use this profile for this command only")
         .option("--json", "emit a JSON object");
     command.action(async (options) => {
         runtime.setJsonMode(options.json === true);
-        const profile = await runtime.resolve();
+        const profile = await runtime.resolve({ profile: options.profile });
         const changes = await refreshStoredMetadata(runtime.env, profile);
         if (options.json === true) {
             runtime.write(`${JSON.stringify({
@@ -223,8 +232,9 @@ function registerClear(parent, runtime) {
     parent
         .command("clear")
         .description("Delete the stored metadata of the active profile")
-        .action(async () => {
-        const profile = await runtime.resolve();
+        .option("--profile <name>", "use this profile for this command only")
+        .action(async (options) => {
+        const profile = await runtime.resolve({ profile: options.profile });
         await clearStoredMetadata(runtime.env, profile);
         runtime.write(`Cleared stored metadata for profile ${profile.name}.\n`);
     });
@@ -236,14 +246,19 @@ function addLookup(parent, runtime, spec, load) {
         setJsonMode: runtime.setJsonMode,
     }));
 }
+/** The `--profile` override a lookup was handed, if any. */
+function profileOverride(options) {
+    return typeof options.profile === "string" ? options.profile : undefined;
+}
 function instanceLoad(runtime) {
-    return async () => loadStoredMetadata(runtime.env, await runtime.resolve());
+    return async (options) => loadStoredMetadata(runtime.env, await runtime.resolve({ profile: profileOverride(options) }));
 }
-/** The active profile under this run's --project override, if any. */
+/** The active profile under this run's --profile/--project overrides. */
 async function projectProfile(runtime, options) {
     const raw = options.project;
     return runtime.resolve({
-        project: parseOptionalId(typeof raw === "string" ? raw : undefined),
+        profile: profileOverride(options),
+        project: parseProjectOverride(typeof raw === "string" ? raw : undefined),
     });
 }
 function projectLoad(runtime) {

package/dist/commands/project.js

@@ -6,7 +6,8 @@ import { flattenHalRecord, toFormattable } from "../core/hal.js";
 import { apiDelete, apiGet, apiPatchRaw, apiPost, apiPostRaw, authenticate, } from "../core/http.js";
 import { DEFAULT_PAGE_SIZE, allPageSize, halElements, parsePageSize, withPageSize, } from "../core/paginate.js";
 import { isIdForm, rankByCloseness, resolveName, } from "../context/resolve.js";
-import { parseOptionalId, } from "../context/profile.js";
+import { parseProjectOverride, } from "../context/profile.js";
+import { PROJECTS_COLLECTION, resolveProjectRef } from "../context/projectref.js";
 export const LIST_COLUMNS = [
     { title: "ID", field: "id" },
     { title: "IDENTIFIER", field: "identifier" },
@@ -33,7 +34,7 @@ async function connect(runtime, options) {
     runtime.setJsonMode(options.json === true);
     const profile = await runtime.resolve({
         profile: options.profile,
-        project: parseOptionalId(options.project),
+        project: parseProjectOverride(options.project),
     });
     return {
         getPage: (path) => apiGet(profile.instanceUrl, profile.apiKey, path),
@@ -42,75 +43,9 @@ async function connect(runtime, options) {
 function collectValue(value, previous) {
     return [...previous, value];
 }
-function hitOf(element) {
-    const candidate = element;
-    return typeof candidate.id === "number"
-        && typeof candidate.identifier === "string"
-        && typeof candidate.name === "string"
-        ? { id: candidate.id, identifier: candidate.identifier, name: candidate.name }
-        : undefined;
-}
-const PROJECTS_COLLECTION = "/api/v3/projects";
 const PRINCIPALS_COLLECTION = "/api/v3/principals";
 const ROLES_COLLECTION = "/api/v3/roles";
 const MEMBERSHIPS_COLLECTION = "/api/v3/memberships";
-/**
- * Every visible project, page by page in server order. Resolution walks
- * instead of filtering server-side because the exact-match filter set
- * differs between instance versions; the collection endpoint does not.
- */
-async function walkProjects(getPage) {
-    const hits = [];
-    for await (const element of halElements(getPage, withPageSize(PROJECTS_COLLECTION, DEFAULT_PAGE_SIZE))) {
-        const hit = hitOf(element);
-        if (hit !== undefined) {
-            hits.push(hit);
-        }
-    }
-    return hits;
-}
-function missingProjectError(raw, known) {
-    return new OpCliError("NOT_FOUND", `project "${raw}" not found.`, known.length > 0
-        ? `known projects, closest first: ${rankByCloseness(raw, known).slice(0, 6).join(", ")}.`
-        : "check the spelling or list projects with op-cli project list.");
-}
-/**
- * Resolve one reference that may be an id, an identifier, or a name.
- * All-digits means an id and is fetched directly. Anything else matches
- * identifier and name exactly across every visible project; one distinct
- * match wins, several distinct projects fail loudly instead of guessing.
- */
-async function resolveProjectRef(getPage, raw) {
-    if (isIdForm(raw)) {
-        try {
-            const hit = hitOf(await getPage(`${PROJECTS_COLLECTION}/${raw}`));
-            if (hit !== undefined) {
-                return hit;
-            }
-            throw new OpCliError("NOT_FOUND", `project "${raw}" not found.`, "check the id; run op-cli project list to see what is visible.");
-        }
-        catch (error) {
-            if (error instanceof OpCliError && error.code === "USAGE_ERROR") {
-                throw error;
-            }
-            if (error instanceof OpCliError && error.code === "NOT_FOUND") {
-                throw new OpCliError("NOT_FOUND", `project "${raw}" not found.`, "check the id; run op-cli project list to see what is visible.");
-            }
-            throw error;
-        }
-    }
-    const all = await walkProjects(getPage);
-    const matches = all.filter((hit) => hit.identifier === raw || hit.name === raw);
-    const distinct = [...new Map(matches.map((hit) => [hit.id, hit])).values()];
-    if (distinct.length === 1) {
-        return distinct[0];
-    }
-    if (distinct.length > 1) {
-        const listed = distinct.map((hit) => `${String(hit.id)} (${hit.name})`).join(", ");
-        throw new OpCliError("USAGE_ERROR", `project "${raw}" is ambiguous. Candidates: ${listed}.`, "repeat the value as the explicit id of one candidate.");
-    }
-    throw missingProjectError(raw, all.flatMap((hit) => [hit.identifier, hit.name]));
-}
 /**
  * One live lookup over an uncached collection. Stored metadata has a
  * refresh to re-read the disk store; here refresh simply walks again.
@@ -276,7 +211,7 @@ export function registerProjectCommands(project, runtime) {
         .option("--limit <n>", "maximum number of results to show")
         .option("--all", "fetch every page instead of one limited page")
         .option("--profile <name>", "use this profile for this command only")
-        .option("--project <id>", "override the profile default project")
+        .option("--project <name-or-id>", "override the profile default project")
         .action(async (options) => {
         runtime.setJsonMode(options.json === true);
         // Flag misuse is refused before any traffic.
@@ -352,7 +287,7 @@ export function registerProjectCommands(project, runtime) {
         .option("--json", "emit a flat JSON record")
         .option("--fields <list>", "comma-separated fields to show")
         .option("--profile <name>", "use this profile for this command only")
-        .option("--project <id>", "override the profile default project")
+        .option("--project <name-or-id>", "override the profile default project")
         .action(async (reference, options) => {
         const { getPage } = await connect(runtime, options);
         const hit = await resolveProjectRef(getPage, reference);
@@ -372,13 +307,13 @@ export function registerProjectCommands(project, runtime) {
         .option("--json", "emit a flat JSON record")
         .option("--fields <list>", "comma-separated fields to show")
         .option("--profile <name>", "use this profile for this command only")
-        .option("--project <id>", "override the profile default project")
+        .option("--project <name-or-id>", "override the profile default project")
         .action(async (name, options) => {
         const identifier = requireIdentifier(options, "create");
         const { getPage } = await connect(runtime, options);
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         const payload = { name, identifier };
         if (options.description !== undefined) {
@@ -408,7 +343,7 @@ export function registerProjectCommands(project, runtime) {
         .option("--json", "emit a flat JSON record")
         .option("--fields <list>", "comma-separated fields to show")
         .option("--profile <name>", "use this profile for this command only")
-        .option("--project <id>", "override the profile default project")
+        .option("--project <name-or-id>", "override the profile default project")
         .action(async (reference, options) => {
         const isPublic = optionalBooleanFlag(options.public !== undefined, options.public, "public");
         const touchesSomething = options.name !== undefined
@@ -420,7 +355,7 @@ export function registerProjectCommands(project, runtime) {
         const { getPage } = await connect(runtime, options);
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         const hit = await resolveProjectRef(getPage, reference);
         const payload = {};
@@ -447,13 +382,13 @@ export function registerProjectCommands(project, runtime) {
         .option("--json", "emit a flat JSON record")
         .option("--fields <list>", "comma-separated fields to show")
         .option("--profile <name>", "use this profile for this command only")
-        .option("--project <id>", "override the profile default project")
+        .option("--project <name-or-id>", "override the profile default project")
         .action(async (reference, name, options) => {
         const identifier = requireIdentifier(options, "copy");
         const { getPage } = await connect(runtime, options);
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         const hit = await resolveProjectRef(getPage, reference);
         const source = (await getPage(`${PROJECTS_COLLECTION}/${String(hit.id)}`));
@@ -478,12 +413,12 @@ export function registerProjectCommands(project, runtime) {
         .description("Mark one project as favourited for the current user")
         .argument("<reference>")
         .option("--profile <name>", "use this profile for this command only")
-        .option("--project <id>", "override the profile default project")
+        .option("--project <name-or-id>", "override the profile default project")
         .action(async (reference, options) => {
         const { getPage } = await connect(runtime, options);
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         const hit = await resolveProjectRef(getPage, reference);
         await apiPost(profile.instanceUrl, profile.apiKey, `${PROJECTS_COLLECTION}/${String(hit.id)}/favorite`, {});
@@ -494,12 +429,12 @@ export function registerProjectCommands(project, runtime) {
         .description("Remove one project from the current user's favourites")
         .argument("<reference>")
         .option("--profile <name>", "use this profile for this command only")
-        .option("--project <id>", "override the profile default project")
+        .option("--project <name-or-id>", "override the profile default project")
         .action(async (reference, options) => {
         const { getPage } = await connect(runtime, options);
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         const hit = await resolveProjectRef(getPage, reference);
         await apiDelete(profile.instanceUrl, profile.apiKey, `${PROJECTS_COLLECTION}/${String(hit.id)}/favorite`);
@@ -519,7 +454,7 @@ export function registerProjectCommands(project, runtime) {
         .option("--json", "emit a flat JSON array")
         .option("--fields <list>", "comma-separated columns to show")
         .option("--profile <name>", "use this profile for this command only")
-        .option("--project <id>", "override the profile default project")
+        .option("--project <name-or-id>", "override the profile default project")
         .action(async (reference, options) => {
         const { getPage } = await connect(runtime, options);
         const hit = await resolveProjectRef(getPage, reference);
@@ -547,13 +482,13 @@ export function registerProjectCommands(project, runtime) {
         .option("--json", "emit a flat JSON record")
         .option("--fields <list>", "comma-separated fields to show")
         .option("--profile <name>", "use this profile for this command only")
-        .option("--project <id>", "override the profile default project")
+        .option("--project <name-or-id>", "override the profile default project")
         .action(async (reference, principal, roles, options) => {
         runtime.setJsonMode(options.json === true);
         const { getPage } = await connect(runtime, options);
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         const hit = await resolveProjectRef(getPage, reference);
         const principalId = await resolvePrincipalId(profile, principal);
@@ -576,12 +511,12 @@ export function registerProjectCommands(project, runtime) {
         .argument("<reference>", "project, by id, identifier, or name")
         .argument("<principal>", "user or group, by name, id, or me")
         .option("--profile <name>", "use this profile for this command only")
-        .option("--project <id>", "override the profile default project")
+        .option("--project <name-or-id>", "override the profile default project")
         .action(async (reference, principal, options) => {
         const { getPage } = await connect(runtime, options);
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         const hit = await resolveProjectRef(getPage, reference);
         const principalId = await resolvePrincipalId(profile, principal);
@@ -624,7 +559,7 @@ export function registerProjectCommands(project, runtime) {
         .argument("<reference>", "project, by id, identifier, or name")
         .option("--yes", "confirm the deletion")
         .option("--profile <name>", "use this profile for this command only")
-        .option("--project <id>", "override the profile default project")
+        .option("--project <name-or-id>", "override the profile default project")
         .action(async (reference, options) => {
         // The guard fires before any resolution or traffic: without --yes
         // nothing is read, nothing is sent, with or without a terminal.
@@ -635,7 +570,7 @@ export function registerProjectCommands(project, runtime) {
         const { getPage } = await connect(runtime, options);
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         const hit = await resolveProjectRef(getPage, reference);
         await apiDelete(profile.instanceUrl, profile.apiKey, `${PROJECTS_COLLECTION}/${String(hit.id)}`);