overlord-cli 5.1.1 → 5.4.0

package/README.md

@@ -6,15 +6,27 @@ Website: [ovld.ai](https://ovld.ai)
 
 ## Install
 
+Note: Use Node.js 20 or newer for every CLI install or update.
+
 Install it globally so the `ovld` and `overlord` commands are available on your `PATH`:
 
 ```bash
 npm install -g overlord-cli
-```
 
-Use Node.js 20 or newer for every CLI install or update.
-Run `ovld update` any time you want to refresh the global npm install to the latest release.
+#After installing, run 
+ovld setup all #to configure every supported connector (`ovld setup` alone is interactive)
 
+#for individual connectors, run `ovld setup <connector>`.
+ovld setup cursor
+ovld setup claude
+ovld setup codex
+ovld setup all
+```
+
+```bash
+# To update the CLI to the latest release, run:
+ovld update
+```
 ## Usage
 
 ```bash
@@ -22,28 +34,36 @@ ovld help
 overlord help
 ```
 
-The CLI exposes the same command set under both names.
-`ovld auth login` opens a browser when possible and also prints a verification URL/code so login can be completed from another machine over SSH.
+### Auth
+```bash
+# Login to Overlord
+ovld auth login #opens a browser when possible and also prints a verification URL/code so login can be completed from another machine over SSH.
+ovld auth status # show current login status (use --verbose for redacted diagnostics)
+ovld auth repair # mirror and chmod shared Desktop/CLI credentials when possible
+ovld auth logout # remove stored credentials
+```
 
 Desktop-installed wrappers default `OVERLORD_URL` to `https://www.ovld.ai` unless you override it explicitly.
 For local dev against the web app on port 3000, export the override before running auth or protocol commands:
-
 ```bash
 export OVERLORD_URL=http://localhost:3000
-ovld auth login
 ```
 
 Common commands:
 
 ```bash
 ovld auth login
+ovld auth status
 ovld attach
 ovld create "Investigate the failing build" --agent codex
 ovld prompt "Draft a fix for the onboarding flow"
+ovld version
 ovld update
 ovld protocol discover-project
 ovld protocol attach --ticket-id <ticket-id>
+ovld protocol search-tickets --query "auth refactor" --status next-up,execute
 ovld protocol update --session-key <session-key> --ticket-id <ticket-id> --summary "Working on it" --phase execute
+ovld setup
 ovld setup codex
 ovld setup claude
 ovld setup cursor
@@ -57,20 +77,49 @@ ovld doctor
 - Node.js 20 or newer
 - Access to an Overlord instance when using authenticated commands
 
-## Commands
+## Commands for Humans
+
+Find full CLI docs here: https://www.ovld.ai/docs/surfaces/cli
+
+Top-level commands (see `ovld help`):
 
-- `attach` - search tickets and launch an agent interactively
-- `create` - create a ticket from a short objective; supports the same delegate-identifying flags as `ovld protocol create` (`--agent`, `--model`, `--delegate`)
-- `prompt` - create a ticket and launch an agent on it
-- `auth` - log in, log out, or check auth status
-- `tickets` - list or create tickets
-- `ticket` - work with a single ticket
-- `protocol` - run ticket lifecycle commands such as `discover-project`, `attach`, `connect`, `load-context`, `spawn`, `update`, `record-change-rationales`, `ask`, `read-context`, `write-context`, `deliver`, and artifact upload/download helpers
-- `connect`, `restart`, `context` - launch or resume an agent session or print ticket context
+- `attach` - search tickets and launch an agent interactively (`ovld attach [ticketId] [agent]`)
+- `create` - create a ticket with numbered project selection; supports `--agent`, `--model`, `--delegate` (same delegate flags as `ovld protocol create`)
+- `prompt` - create a ticket, then launch an agent on it
+- `auth` - `login`, `status`, `repair` (shared Desktop/CLI credentials), or `logout`
+- `tickets` - `create` or `list` (optional `--status`)
+- `ticket` - `context <ticketId>` to print context for one ticket
+- `connect`, `restart`, `context` - launch or resume an agent session, or print ticket context (`context` requires `TICKET_ID`)
 - `run`, `resume` - legacy aliases for `connect` and `restart`
-- `setup` - prepare the Overlord plugin or connector for a supported agent; `ovld setup claude` performs the one-time v3.25.0 to v4 Claude plugin migration
+- `setup` - install the Overlord connector for an agent; `ovld setup [agent|all]` (interactive with no args). `ovld setup claude` also performs the one-time v3.25.0 to v4 Claude plugin migration
 - `update` - install the latest CLI release from npm
-- `doctor` - verify installed agent connectors and check whether a newer CLI version is available
+- `doctor` - validate installed connectors and check for CLI updates
+- `version` - print the installed CLI version
+
+## Commands for agents
+Agents can find docs here: https://www.ovld.ai/docs/for-agents
+
+`ovld protocol <subcommand>` is the surface agents and hooks use for ticket lifecycle work. Run `ovld protocol help` for flags, env fallbacks, and examples.
+
+- `auth-status` - return machine-readable auth status for agent runtimes
+- `discover-project` - resolve a project from the current (or given) working directory
+- `attach` - start a ticket session and return full working context
+- `connect` - start a lightweight session without full context
+- `load-context` - read ticket context without creating a session
+- `search-tickets` - find tickets by keyword, status, project, creator, or update date
+- `create` - create a draft ticket without attaching (standalone or follow-up)
+- `spawn` - create a follow-up ticket and attach to it immediately
+- `update` - post progress, activity events, and optional change rationales
+- `record-change-rationales` - persist structured change rationales without a normal progress update
+- `ask` - post a blocking question and move the ticket to review
+- `permission-request` - notify Overlord that the agent is requesting tool permission
+- `read-context` - read shared persistent context for this ticket
+- `write-context` - write shared persistent context for future sessions
+- `deliver` - finish work, send artifacts, and move the ticket to review
+- `artifact-prepare-upload` - get a signed upload URL for a ticket artifact
+- `artifact-finalize-upload` - finalize an uploaded artifact row after storage upload
+- `artifact-download-url` - get a signed download URL for an existing artifact
+- `artifact-upload-file` - prepare, upload, and finalize a local file in one command
 
 ## License
 

package/bin/_cli/protocol.mjs

@@ -601,7 +601,7 @@ async function protocolRecordChangeRationales(args) {
     bearerToken,
     localSecret,
     organizationId,
-    '/api/protocol/change-rationales',
+    '/api/protocol/record-change-rationales',
     body,
     timeoutMs
   );
@@ -1202,6 +1202,47 @@ async function protocolCreateTicket(args) {
   console.log(JSON.stringify(data, null, 2));
 }
 
+// ---------------------------------------------------------------------------
+// search-tickets (find tickets by query/status/project/created_by/dates)
+// ---------------------------------------------------------------------------
+
+async function protocolSearchTickets(args) {
+  const flags = parseFlags(args);
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const timeoutMs = resolveTimeout(flags);
+
+  const statuses = flags.status
+    ? String(flags.status)
+        .split(',')
+        .map(s => s.trim())
+        .filter(Boolean)
+    : undefined;
+
+  const body = {
+    ...(flags.query ? { query: String(flags.query) } : {}),
+    ...(statuses?.length ? { statuses } : {}),
+    ...(flags['include-completed'] !== undefined
+      ? { includeCompleted: flags['include-completed'] !== false && flags['include-completed'] !== 'false' }
+      : {}),
+    ...(flags.limit ? { limit: parseInt(String(flags.limit), 10) } : {}),
+    ...(flags['project-id'] ? { projectId: String(flags['project-id']) } : {}),
+    ...(flags['created-by'] ? { createdBy: String(flags['created-by']) } : {}),
+    ...(flags['updated-after'] ? { updatedAfter: String(flags['updated-after']) } : {}),
+    ...(flags['updated-before'] ? { updatedBefore: String(flags['updated-before']) } : {})
+  };
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/search-tickets',
+    body,
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+}
+
 // ---------------------------------------------------------------------------
 // auth-status (agent-friendly auth diagnostics)
 // ---------------------------------------------------------------------------
@@ -1263,6 +1304,7 @@ Subcommands:
   attach                    Start a ticket session and return full working context
   connect                   Start a lightweight session without full context
   load-context              Read ticket context without creating a session
+  search-tickets            Find tickets by keyword, status, project, creator, or update date
   create                    Create a draft ticket without attaching (follow-up or standalone)
   spawn                     Create a follow-up ticket and attach to it immediately
   update                    Post progress, activity events, and optional change rationales
@@ -1344,6 +1386,22 @@ load-context:
   Required:
     --ticket-id <id>
 
+search-tickets:
+  Purpose:
+    Find tickets in your organization by keyword, status, project, creator, or update window.
+    Omit --query to list mode (most recently updated first).
+  Optional:
+    --query <text>             Free-text search across the ticket search vector + title fallback
+    --status <csv>             Comma-separated statuses, e.g. "draft,next-up,execute"
+    --include-completed <bool> Include completed tickets (default: false)
+    --limit <n>                Max results 1..50 (default: 8)
+    --project-id <uuid>        Restrict to a single project
+    --created-by <uuid>        Restrict to tickets created by this user
+    --updated-after <iso>      Updated_at >= ISO timestamp
+    --updated-before <iso>     Updated_at <= ISO timestamp
+  Returns:
+    JSON with { tickets, count }.
+
 update:
   Purpose:
     Post progress or activity events during execution
@@ -1541,6 +1599,7 @@ Examples:
   ovld protocol attach --ticket-id abc-123 --external-session-id null
   ovld protocol connect --ticket-id abc-123
   ovld protocol load-context --ticket-id abc-123
+  ovld protocol search-tickets --query "auth refactor" --status next-up,execute --limit 10
   ovld protocol create --agent codex --objective "Capture follow-up work from this repo"
   ovld protocol create --agent codex --session-key <key> --ticket-id <id> --objective "Capture follow-up work"
   ovld protocol spawn --agent codex --objective "Implement user auth" --priority high
@@ -1568,6 +1627,7 @@ Examples:
   if (subcommand === 'attach') { await protocolAttach(args); return; }
   if (subcommand === 'connect') { await protocolConnect(args); return; }
   if (subcommand === 'load-context') { await protocolLoadContext(args); return; }
+  if (subcommand === 'search-tickets') { await protocolSearchTickets(args); return; }
   if (subcommand === 'create' || subcommand === 'create-ticket') { await protocolCreateTicket(args); return; }
   if (subcommand === 'spawn') { await protocolSpawn(args); return; }
   if (subcommand === 'artifact-prepare-upload') { await protocolArtifactPrepareUpload(args); return; }

package/bin/_cli/tickets.mjs

@@ -67,7 +67,7 @@ export async function ticketsList(args) {
   };
 
   const data = await apiPost(
-    `${platformUrl}/api/protocol/list-tickets`,
+    `${platformUrl}/api/protocol/search-tickets`,
     bearerToken,
     localSecret,
     organizationId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "5.1.1",
+  "version": "5.4.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "type": "module",
   "bin": {

package/plugins/claude/skills/overlord-ticket/SKILL.md

@@ -127,6 +127,15 @@ ovld protocol discover-project
 
 You can override with `--project-id` or `--working-directory` if needed.
 
+### Choosing `--execution-target`
+
+Pass `--execution-target agent` or `--execution-target human` (default: `human`) when creating tickets.
+
+- **`agent`** — any task an AI agent can complete in a computer environment: coding, internet research, document editing, data analysis, automated testing, etc.
+- **`human`** — any task requiring human presence or judgment: setting credentials or tokens in a third-party UI (e.g. Vercel, AWS), sending physical mail, making a product or business decision, physical-world actions.
+
+When in doubt, ask yourself: *can this be done entirely inside a terminal or browser by an AI without human intervention?* If yes → `agent`. If it requires a human to log in, decide, or act in the real world → `human`.
+
 ## Context And Artifacts
 
 ```bash
@@ -145,3 +154,5 @@ ovld protocol artifact-download-url --session-key <sessionKey> --ticket-id $TICK
 - Use `write-context` for facts a future agent session should know.
 - Do not add or commit changes unless the user explicitly asks you to commit.
 - Delivery is the concluding step. After delivering, stop unless the user follows up or the ticket is reopened.
+
+<!-- version: 0.2.2 -->

package/plugins/cursor/skills/overlord-ticket/SKILL.md

@@ -27,9 +27,21 @@ Use this skill whenever Cursor needs to work with Overlord, whether the session
 6. If you need other lifecycle commands or flags, run `ovld protocol help` and use the real subcommand list instead of guessing.
 7. Once you attach to a ticket, switch back to Mode 1 and follow the full ticket lifecycle.
 
+## Choosing `--execution-target` When Creating Tickets
+
+Pass `--execution-target agent` or `--execution-target human` (default: `human`) when creating tickets.
+
+- **`agent`** — any task an AI agent can complete in a computer environment: coding, internet research, document editing, data analysis, automated testing, etc.
+- **`human`** — any task requiring human presence or judgment: setting credentials or tokens in a third-party UI (e.g. Vercel, AWS), sending physical mail, making a product or business decision, physical-world actions.
+
+When in doubt, ask yourself: *can this be done entirely inside a terminal or browser by an AI without human intervention?* If yes → `agent`. If it requires a human to log in, decide, or act in the real world → `human`.
+
 ## Rules
 
 - Always attach first and always deliver last once you are on a ticket.
 - Use `ovld protocol` commands, the plugin commands, and the MCP tool instead of ad hoc scripts.
 - Do not invent protocol subcommands. Use `ovld protocol help` when unsure.
 - Include at least one progress update before delivering.
+- When creating follow-up tickets, always set `--execution-target` explicitly using the `agent`/`human` rule above.
+
+<!-- version: 0.2.2 -->

package/plugins/overlord/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Chat-driven access to Overlord ticket protocol workflows.",
   "author": {
     "name": "Cooperativ",
@@ -23,9 +23,9 @@
     "privacyPolicyURL": "https://www.ovld.ai/privacy",
     "termsOfServiceURL": "https://www.ovld.ai/terms",
     "defaultPrompt": [
-      "Attach to Overlord ticket 123 and summarize the context before editing code",
-      "Post an execute update to this Overlord ticket after a meaningful implementation step",
-      "Deliver this Overlord ticket with artifacts and change rationales"
+      "Create an Overlord ticket with the objective 'Implement feature X' and summarize the context before editing code",
+      "Execute Overlord ticket [ticket-id]",
+      "Find all Overlord tickets with the status 'next-up' and prioritize the most important one"
     ],
     "brandColor": "#1E6B5C",
     "composerIcon": "./assets/icon.png",

package/plugins/overlord/README.md

@@ -24,7 +24,7 @@ personal marketplace entry at `~/.agents/plugins/marketplace.json`.
 - Ticket session flow: `attach_ticket`, `connect_ticket`, `load_ticket_context`, `spawn_ticket`
 - Progress and review flow: `post_update`, `record_change_rationales`, `ask_blocking_question`, `deliver_ticket`
 - Shared context: `read_shared_context`, `write_shared_context`
-- Artifacts: `artifact_prepare_upload`, `artifact_finalize_upload`, `artifact_download_url`, `artifact_upload_file`
+- Artifacts: `prepare_artifact_upload`, `finalize_artifact_upload`, `get_artifact_download_url`, `upload_artifact_file`
 
 The MCP server shells into the installed `ovld` binary so the plugin stays aligned with the shipped CLI behavior instead of depending on this repository checkout.
 

package/plugins/overlord/scripts/overlord-mcp.mjs

@@ -296,7 +296,7 @@ const tools = [
     subcommand: 'deliver'
   },
   {
-    name: 'artifact_prepare_upload',
+    name: 'prepare_artifact_upload',
     description: 'Prepare an Overlord artifact upload and return a signed upload URL.',
     inputSchema: {
       type: 'object',
@@ -325,7 +325,7 @@ const tools = [
     subcommand: 'artifact-prepare-upload'
   },
   {
-    name: 'artifact_finalize_upload',
+    name: 'finalize_artifact_upload',
     description: 'Finalize an artifact after uploading bytes to the signed storage URL.',
     inputSchema: {
       type: 'object',
@@ -354,7 +354,7 @@ const tools = [
     subcommand: 'artifact-finalize-upload'
   },
   {
-    name: 'artifact_download_url',
+    name: 'get_artifact_download_url',
     description: 'Create a signed download URL for an uploaded Overlord artifact.',
     inputSchema: {
       type: 'object',
@@ -377,7 +377,7 @@ const tools = [
     subcommand: 'artifact-download-url'
   },
   {
-    name: 'artifact_upload_file',
+    name: 'upload_artifact_file',
     description: 'Prepare, upload, and finalize a local file as an Overlord artifact in one step.',
     inputSchema: {
       type: 'object',

package/plugins/overlord/skills/overlord-ticket/SKILL.md

@@ -121,6 +121,15 @@ ovld protocol create --agent codex --objective "Capture follow-up work from this
 ovld protocol spawn --agent codex --objective "Implement feature X" --priority medium
 ```
 
+### Choosing `--execution-target`
+
+Pass `--execution-target agent` or `--execution-target human` (default: `human`) when creating tickets.
+
+- **`agent`** — any task an AI agent can complete in a computer environment: coding, internet research, document editing, data analysis, automated testing, etc.
+- **`human`** — any task requiring human presence or judgment: setting credentials or tokens in a third-party UI (e.g. Vercel, AWS), sending physical mail, making a product or business decision, physical-world actions.
+
+When in doubt, ask yourself: *can this be done entirely inside a terminal or browser by an AI without human intervention?* If yes → `agent`. If it requires a human to log in, decide, or act in the real world → `human`.
+
 ## Rules
 
 - The authoritative lifecycle is the `ovld protocol` CLI once you are on a ticket.
@@ -128,3 +137,5 @@ ovld protocol spawn --agent codex --objective "Implement feature X" --priority m
 - Prefer the installed `ovld` CLI and the plugin's MCP tools instead of ad hoc repo scripts.
 - Do not create or rely on a local Codex `AGENTS.md` bundle for Overlord.
 - When the ticket was launched by Overlord, the ticket prompt remains authoritative for the specific task objective and ticket-level constraints.
+
+<!-- version: 0.2.2 -->