@mcowger/plexus-cli 0.0.40 → 0.0.42

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mcowger/plexus-cli",
3
- "version": "0.0.40",
3
+ "version": "0.0.42",
4
4
  "description": "Dynamic command line client for Plexus management APIs",
5
5
  "repository": {
6
6
  "type": "git",
@@ -1,24 +1,40 @@
1
1
  ---
2
2
  name: plexus-cli
3
3
  description: >-
4
- Use this skill to inspect or administer a running Plexus instance through
5
- plexuscli. Use it before plexus-rest-api whenever `bun run plexuscli` or
6
- `plexuscli` is available; it is the preferred interface for live
7
- request/debug-trace/error/system-log review and runtime configuration.
4
+ Use this skill to inspect or administer a running Plexus instance. Prefer
5
+ Plexus MCP tools when available; they are more efficient than CLI or REST
6
+ calls. Fall back to `bun run plexuscli` or `plexuscli`, then plexus-rest-api,
7
+ for live request/debug-trace/error/system-log review and runtime configuration.
8
8
  ---
9
9
 
10
10
  # Plexus Management CLI
11
11
 
12
- Use `plexuscli` to call the Management API. The CLI discovers the running
13
- server's public OpenAPI document on each invocation, so use `api list` and
14
- `api describe` when an operation ID is uncertain.
12
+ Prefer Plexus MCP tools to call the Management API. When MCP is unavailable
13
+ for the target instance or required operation, use `plexuscli`. The CLI
14
+ discovers the running server's public OpenAPI document on each invocation,
15
+ so use `api list` and `api describe` when an operation ID is uncertain.
15
16
 
16
17
  ## Preference
17
18
 
18
- Use this skill whenever either `bun run plexuscli --help` or
19
- `plexuscli --help` succeeds. Use `plexus-rest-api` only when neither command
20
- is available or when this CLI intentionally does not support the required API
21
- operation, such as SSE streaming.
19
+ 1. Use the available Plexus MCP tools first. Confirm they target the intended
20
+ instance and support the required operation. Discover their tool schemas
21
+ rather than guessing tool names or arguments. Do not run CLI commands or
22
+ raw REST calls for an operation MCP can perform.
23
+ 2. Fall back to the CLI when MCP is unavailable for the target instance or
24
+ does not support the required operation, and either `bun run plexuscli --help`
25
+ or `plexuscli --help` succeeds.
26
+ 3. Use `plexus-rest-api` only when neither MCP nor the CLI is available for
27
+ the required operation, such as SSE streaming unsupported by both.
28
+
29
+ The setup and command examples below apply to the CLI fallback. With MCP,
30
+ use its configured connection; the same secret-handling and runtime-change
31
+ precautions apply. Do not switch interfaces to bypass authentication,
32
+ validation, or permission errors.
33
+
34
+ With any interface, never print supplied keys and avoid broad key/config
35
+ reads unless the user requested them. Run delete, restore, restart, reset,
36
+ clear, rotate, or disable operations only when the user explicitly requested
37
+ that action; do not rely on MCP tools to prompt for confirmation.
22
38
 
23
39
  ## Local Dev Setup
24
40
 
package/src/skill.ts CHANGED
@@ -1 +1 @@
1
- export const plexusCliSkill = "---\nname: plexus-cli\ndescription: >-\n Use this skill to inspect or administer a running Plexus instance through\n plexuscli. Use it before plexus-rest-api whenever `bun run plexuscli` or\n `plexuscli` is available; it is the preferred interface for live\n request/debug-trace/error/system-log review and runtime configuration.\n---\n\n# Plexus Management CLI\n\nUse `plexuscli` to call the Management API. The CLI discovers the running\nserver's public OpenAPI document on each invocation, so use `api list` and\n`api describe` when an operation ID is uncertain.\n\n## Preference\n\nUse this skill whenever either `bun run plexuscli --help` or\n`plexuscli --help` succeeds. Use `plexus-rest-api` only when neither command\nis available or when this CLI intentionally does not support the required API\noperation, such as SSE streaming.\n\n## Local Dev Setup\n\nGet the active worktree server port; do not derive it manually:\n\n```bash\nPORT=$(bun run dev:get:port)\nexport PLEXUS_URL=\"http://localhost:$PORT\"\n```\n\nThe standard local dev stack uses `password` as its admin key. This is for\nlocal development only; never assume it for staging or production.\n\n```bash\nexport PLEXUS_ADMIN_KEY=password\n```\n\nRun the checkout-local CLI:\n\n```bash\nPLEXUSCLI='bun run plexuscli'\n```\n\nAfter installation, use `PLEXUSCLI=plexuscli` instead. Verify access before\nmaking a change:\n\n```bash\n$PLEXUSCLI api call getV0ManagementAuthVerify\n```\n\nFor a remote instance, require `PLEXUS_URL` and `PLEXUS_ADMIN_KEY` from the\nuser. Never print a supplied key. The CLI does not redact API responses, so\navoid broad key/config reads unless the user requested them.\n\n## CLI Conventions\n\n- `api list` prints the available supported management operations.\n- `api describe <operationId>` shows parameters and body requirements.\n- `api call <operationId>` invokes an operation. An operation ID alone is a\n shorthand for `api call`.\n- Use `--param name=value` for path/query parameters. JSON literals are\n coerced, so `--param limit=50` is numeric and\n `--param fields='[\"requestId\"]'` is an array.\n- Use `--body '{...}'` or `--body-file payload.json` for writes.\n- Use `--output json|yaml|table`. Non-interactive output defaults to JSON;\n interactive output defaults to a deterministic table.\n- Use `--all` only for standardized paginated list operations.\n- `DELETE` and operations named delete, restore, restart, reset, clear,\n rotate, or disable prompt for confirmation. Use `--yes` only when the user\n explicitly requested that action.\n- The CLI deliberately hides SSE operations, including live system-log\n streaming. Use the recent-log endpoint instead.\n\n## Common Read Workflows\n\n### Inspect Available Operations\n\n```bash\n$PLEXUSCLI api list --output table\n$PLEXUSCLI api describe getV0ManagementDebugLogs --output yaml\n```\n\n### Review Debug Trace Configuration\n\nDebug capture configuration is in memory and resets when Plexus restarts.\nCapture is inclusive: global capture, key targets, alias targets, and provider\ntargets each independently cause a trace to be captured.\n\n```bash\n$PLEXUSCLI api call getV0ManagementDebug\n```\n\n### Review Recent Debug Traces\n\nList newest traces, then request the full trace by ID:\n\n```bash\n$PLEXUSCLI api call getV0ManagementDebugLogs --param limit=50\n\n$PLEXUSCLI api call getV0ManagementDebugLogsByrequestId \\\n --param requestId='<request-id>' \\\n --output json\n```\n\nTrace payloads and headers can contain customer data or secrets. Report only\nthe specific redacted fields needed to diagnose the issue.\n\n### Review Inference Errors\n\n```bash\n$PLEXUSCLI api call getV0ManagementErrors --param limit=50\n\n# Retrieve every documented error page only when the user needs the full set.\n$PLEXUSCLI api call getV0ManagementErrors --all --param limit=100\n```\n\n### Review Recent System Logs\n\n```bash\n$PLEXUSCLI api call getV0SystemLogsRecent --param limit=100\n\n$PLEXUSCLI api call getV0SystemLogsRecent --all --param limit=100\n```\n\nThe recent-log endpoint is bounded in memory. It is not a persistent audit\nlog, and `--all` can only retrieve entries the server still retains.\n\n## Runtime Configuration Workflows\n\nInspect the current state before changing it. State the intended change to the\nuser, then send the smallest PATCH/PUT body that satisfies the API.\n\n### Adjust Debug Trace Capture\n\nEnable temporary global capture:\n\n```bash\n$PLEXUSCLI api call patchV0ManagementDebug --body '{\"enabled\":true}'\n```\n\nCapture only selected request dimensions while global capture stays off:\n\n```bash\n$PLEXUSCLI api call patchV0ManagementDebug \\\n --body '{\"enabled\":false,\"keys\":[\"mobile-app\"],\"aliases\":[\"support\"],\"providers\":[\"openai\"]}'\n```\n\nClear provider targeting and disable global capture after the investigation:\n\n```bash\n$PLEXUSCLI api call patchV0ManagementDebug \\\n --body '{\"enabled\":false,\"providers\":null}'\n```\n\n`keys`, `aliases`, and `providers` replace their corresponding target lists;\nsend `null` or `[]` to clear one. Do not leave broad debug capture enabled\nlonger than required.\n\n### Adjust Runtime Log Verbosity\n\nRead the current and startup log levels:\n\n```bash\n$PLEXUSCLI api call getV0ManagementLoggingLevel\n```\n\nIncrease temporary detail:\n\n```bash\n$PLEXUSCLI api call putV0ManagementLoggingLevel --body '{\"level\":\"debug\"}'\n```\n\nValid levels, least to most verbose: `error`, `warn`, `info`, `debug`,\n`verbose`, `silly`. The setting is runtime-only and reverts on restart.\n\nReset it to the startup default only when explicitly requested:\n\n```bash\n$PLEXUSCLI api call deleteV0ManagementLoggingLevel --yes\n```\n\n## Failure Handling\n\n- If spec discovery fails, confirm the URL with `bun run dev:get:port` locally\n or ask for the remote base URL.\n- If an operation ID is unavailable, run `api list`; do not guess a path or\n substitute raw HTTP requests.\n- On HTTP validation errors, report the exact response and stop rather than\n guessing a new payload.\n- For a 401/403, verify the correct `PLEXUS_ADMIN_KEY` was supplied and do not\n retry with unrelated credentials.\n";
1
+ export const plexusCliSkill = "---\nname: plexus-cli\ndescription: >-\n Use this skill to inspect or administer a running Plexus instance. Prefer\n Plexus MCP tools when available; they are more efficient than CLI or REST\n calls. Fall back to `bun run plexuscli` or `plexuscli`, then plexus-rest-api,\n for live request/debug-trace/error/system-log review and runtime configuration.\n---\n\n# Plexus Management CLI\n\nPrefer Plexus MCP tools to call the Management API. When MCP is unavailable\nfor the target instance or required operation, use `plexuscli`. The CLI\ndiscovers the running server's public OpenAPI document on each invocation,\nso use `api list` and `api describe` when an operation ID is uncertain.\n\n## Preference\n\n1. Use the available Plexus MCP tools first. Confirm they target the intended\n instance and support the required operation. Discover their tool schemas\n rather than guessing tool names or arguments. Do not run CLI commands or\n raw REST calls for an operation MCP can perform.\n2. Fall back to the CLI when MCP is unavailable for the target instance or\n does not support the required operation, and either `bun run plexuscli --help`\n or `plexuscli --help` succeeds.\n3. Use `plexus-rest-api` only when neither MCP nor the CLI is available for\n the required operation, such as SSE streaming unsupported by both.\n\nThe setup and command examples below apply to the CLI fallback. With MCP,\nuse its configured connection; the same secret-handling and runtime-change\nprecautions apply. Do not switch interfaces to bypass authentication,\nvalidation, or permission errors.\n\nWith any interface, never print supplied keys and avoid broad key/config\nreads unless the user requested them. Run delete, restore, restart, reset,\nclear, rotate, or disable operations only when the user explicitly requested\nthat action; do not rely on MCP tools to prompt for confirmation.\n\n## Local Dev Setup\n\nGet the active worktree server port; do not derive it manually:\n\n```bash\nPORT=$(bun run dev:get:port)\nexport PLEXUS_URL=\"http://localhost:$PORT\"\n```\n\nThe standard local dev stack uses `password` as its admin key. This is for\nlocal development only; never assume it for staging or production.\n\n```bash\nexport PLEXUS_ADMIN_KEY=password\n```\n\nRun the checkout-local CLI:\n\n```bash\nPLEXUSCLI='bun run plexuscli'\n```\n\nAfter installation, use `PLEXUSCLI=plexuscli` instead. Verify access before\nmaking a change:\n\n```bash\n$PLEXUSCLI api call getV0ManagementAuthVerify\n```\n\nFor a remote instance, require `PLEXUS_URL` and `PLEXUS_ADMIN_KEY` from the\nuser. Never print a supplied key. The CLI does not redact API responses, so\navoid broad key/config reads unless the user requested them.\n\n## CLI Conventions\n\n- `api list` prints the available supported management operations.\n- `api describe <operationId>` shows parameters and body requirements.\n- `api call <operationId>` invokes an operation. An operation ID alone is a\n shorthand for `api call`.\n- Use `--param name=value` for path/query parameters. JSON literals are\n coerced, so `--param limit=50` is numeric and\n `--param fields='[\"requestId\"]'` is an array.\n- Use `--body '{...}'` or `--body-file payload.json` for writes.\n- Use `--output json|yaml|table`. Non-interactive output defaults to JSON;\n interactive output defaults to a deterministic table.\n- Use `--all` only for standardized paginated list operations.\n- `DELETE` and operations named delete, restore, restart, reset, clear,\n rotate, or disable prompt for confirmation. Use `--yes` only when the user\n explicitly requested that action.\n- The CLI deliberately hides SSE operations, including live system-log\n streaming. Use the recent-log endpoint instead.\n\n## Common Read Workflows\n\n### Inspect Available Operations\n\n```bash\n$PLEXUSCLI api list --output table\n$PLEXUSCLI api describe getV0ManagementDebugLogs --output yaml\n```\n\n### Review Debug Trace Configuration\n\nDebug capture configuration is in memory and resets when Plexus restarts.\nCapture is inclusive: global capture, key targets, alias targets, and provider\ntargets each independently cause a trace to be captured.\n\n```bash\n$PLEXUSCLI api call getV0ManagementDebug\n```\n\n### Review Recent Debug Traces\n\nList newest traces, then request the full trace by ID:\n\n```bash\n$PLEXUSCLI api call getV0ManagementDebugLogs --param limit=50\n\n$PLEXUSCLI api call getV0ManagementDebugLogsByrequestId \\\n --param requestId='<request-id>' \\\n --output json\n```\n\nTrace payloads and headers can contain customer data or secrets. Report only\nthe specific redacted fields needed to diagnose the issue.\n\n### Review Inference Errors\n\n```bash\n$PLEXUSCLI api call getV0ManagementErrors --param limit=50\n\n# Retrieve every documented error page only when the user needs the full set.\n$PLEXUSCLI api call getV0ManagementErrors --all --param limit=100\n```\n\n### Review Recent System Logs\n\n```bash\n$PLEXUSCLI api call getV0SystemLogsRecent --param limit=100\n\n$PLEXUSCLI api call getV0SystemLogsRecent --all --param limit=100\n```\n\nThe recent-log endpoint is bounded in memory. It is not a persistent audit\nlog, and `--all` can only retrieve entries the server still retains.\n\n## Runtime Configuration Workflows\n\nInspect the current state before changing it. State the intended change to the\nuser, then send the smallest PATCH/PUT body that satisfies the API.\n\n### Adjust Debug Trace Capture\n\nEnable temporary global capture:\n\n```bash\n$PLEXUSCLI api call patchV0ManagementDebug --body '{\"enabled\":true}'\n```\n\nCapture only selected request dimensions while global capture stays off:\n\n```bash\n$PLEXUSCLI api call patchV0ManagementDebug \\\n --body '{\"enabled\":false,\"keys\":[\"mobile-app\"],\"aliases\":[\"support\"],\"providers\":[\"openai\"]}'\n```\n\nClear provider targeting and disable global capture after the investigation:\n\n```bash\n$PLEXUSCLI api call patchV0ManagementDebug \\\n --body '{\"enabled\":false,\"providers\":null}'\n```\n\n`keys`, `aliases`, and `providers` replace their corresponding target lists;\nsend `null` or `[]` to clear one. Do not leave broad debug capture enabled\nlonger than required.\n\n### Adjust Runtime Log Verbosity\n\nRead the current and startup log levels:\n\n```bash\n$PLEXUSCLI api call getV0ManagementLoggingLevel\n```\n\nIncrease temporary detail:\n\n```bash\n$PLEXUSCLI api call putV0ManagementLoggingLevel --body '{\"level\":\"debug\"}'\n```\n\nValid levels, least to most verbose: `error`, `warn`, `info`, `debug`,\n`verbose`, `silly`. The setting is runtime-only and reverts on restart.\n\nReset it to the startup default only when explicitly requested:\n\n```bash\n$PLEXUSCLI api call deleteV0ManagementLoggingLevel --yes\n```\n\n## Failure Handling\n\n- If spec discovery fails, confirm the URL with `bun run dev:get:port` locally\n or ask for the remote base URL.\n- If an operation ID is unavailable, run `api list`; do not guess a path or\n substitute raw HTTP requests.\n- On HTTP validation errors, report the exact response and stop rather than\n guessing a new payload.\n- For a 401/403, verify the correct `PLEXUS_ADMIN_KEY` was supplied and do not\n retry with unrelated credentials.\n";