feat: agent CLI — JSON envelopes, cloud run/jobs, fragments, projects, CQL, structured errors

[skishore23]

Summary

Turns comfy-cli into an agent-first CLI for ComfyUI — letting an agent (or a human) build, validate, run, and review workflows on a local server or Comfy Cloud entirely from the terminal.

Three ideas hold it together:

1. One machine contract — every command emits the same versioned JSON envelope; every error has a registered code + actionable hint. Agents never parse prose.
2. One graph, composed from pieces — author small typed fragments and compose them with YAML blueprints instead of hand-writing large workflow JSON.
3. Async by default — submit returns immediately, a detached watcher tracks the job, and any later process resumes from a state file.

What's in it

• Machine output (output/) — JSON/NDJSON envelopes, schema registry, comfy discover; auto-JSON on non-TTY.
• Composition (fragments.py, command/workflow_fragments.py) — fragments + blueprints, foreach fan-out, $asset/$item/$var/$alias refs.
• Validation (cql/) — pure-Python engine validates a graph against the live server's object_info before spending.
• Execution (command/jobs.py, jobs_state.py) — async run, detached watcher, resumable job state, item-named outputs.
• Project convention (project.py) — project/1 layout, assets push + lock, run journal, --where routing (OAuth-first credentials).
• Skills (skills/) — bundled SKILL.md files that teach agents to drive the CLI.

Notes for reviewers

• Large branch — it lands the full agent-CLI surface, so it's best reviewed by area (the package list above maps to the sections of work). A detailed architecture walkthrough is available on request.
• No breaking changes to existing human-facing commands; pretty output is byte-identical in a TTY.

Verification

• Full suite green on the CI toolchain (Python 3.10, latest click/typer/rich): 2277 passed, 35 skipped.
• All CI checks pass: build, test, ruff, CodeQL, Socket, Codecov, CodeRabbit, and cross-platform (ubuntu/macOS/windows) + GPU e2e.
• CodeRabbit review addressed (34 fixed; 5 skipped with rationale in-thread).

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds pinned tooling and CI tweaks, a plaintext auth store and OAuth flows, caller and cancellation primitives, a unified HTTP Client, local WebSocket and cloud run paths with job-state persistence/watcher, fragment composition, a full CQL graph engine/loader, many new Typer subcommands, discovery/help JSON, and an error-code registry — auth to cloud, tools endowed (impish rhyme allowed).

Changes

CLI expansion and runtime support

Layer / File(s)	Summary
Auth, cloud, and OAuth foundation comfy_cli/auth/*, comfy_cli/cloud/*, .pre-commit-config.yaml, .github/workflows/ruff_check.yml	Adds plaintext secrets store, comfy auth commands, cloud config resolution, full OAuth (PKCE) flow, pinned ruff/pre-commit version, and workflow CI pin.
CLI entry, routing, and HTTP client comfy_cli/cmdline.py, comfy_cli/comfy_client.py, comfy_cli/output/*, comfy_cli/credentials.py	Expands global CLI flags (--json, --where), installs SIGINT handling/cancellation, and adds unified Client with OAuth/reactive refresh, safe redirects, retries, and output extraction.
Command wiring and generate updates comfy_cli/command/__init__.py, comfy_cli/command/generate/*, comfy_cli/command/install.py	Eager command exports, generate --emit-workflow support, OAuth-first credential resolution for partner calls, and output/print wiring to unified renderer.
Jobs, models, nodes, project, launch comfy_cli/command/jobs.py, job_watcher.py, models/*, nodes.py, project.py, launch.py	Adds comfy jobs suite, background watcher, models/nodes discovery/search, project init/status/assets push, and launch output tweaks.
Run execution package comfy_cli/command/run/*, comfy_cli/command/run/__init__.py	Replaces monolithic run module with a run package: loaders, preflight, execution (WebSocket loop), cloud execute, watcher spawning, job-state persistence, and credentials injection.
Setup, templates, transfer, workflow editing comfy_cli/command/setup.py, templates.py, transfer.py, workflow*.py	Interactive comfy setup wizard, templates gallery commands, upload/download transfer tooling, and frontend-format workflow slot editing & cloud workflow CRUD.
Fragments and CQL engine comfy_cli/fragments.py, comfy_cli/cql/*, comfy_cli/cql/data/*	Typed fragment composition engine, foreach/chunking, and a full CQL graph engine + resilient object_info loader plus bundled node metadata/annotations.
Discovery, help JSON, and errors comfy_cli/discovery.py, comfy_cli/help_json.py, comfy_cli/error_codes.py, comfy_cli/execution_errors.py	Adds machine-help JSON, discovery document builder, canonical error-code registry, and execution-failure classification helpers.
Locking, jobs state, output package comfy_cli/locking.py, comfy_cli/jobs_state.py, comfy_cli/output/__init__.py	Cross-platform file lock utility, durable job state format with atomic writes, and public output renderer exports.
Misc docs & config README.md, .gitignore, .github/workflows/pytest.yml	Docs updated with features/quickstart, gitignore expanded for local artifacts, and test workflow adds jsonschema dependency.

Possibly related PRs:

• Comfy-Org/comfy-cli#455: Related to NDJSON/--json wiring and run command streaming changes.
• Comfy-Org/comfy-cli#452: Related generate command work and supporting client/schema updates.

(An imp tipped the stack — please read layers in order for coherent review.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent-cli

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch agent-cli

[coderabbitai]

Actionable comments posted: 39

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@comfy_cli/auth/store.py`:
- Around line 187-200: The function name set shadows Python's built-in set;
rename the function to a clearer name (e.g., store or upsert) by renaming the
definition def set(...) to def store(...) (or def upsert(...)) and update all
internal references and exports accordingly (any call sites in this module,
imports elsewhere, and __all__ if present) so callers use the new name; keep the
implementation logic and signature the same and add a short compatibility shim
(optional) that forwards the old name to the new function if you need
back-compatibility.

In `@comfy_cli/cancellation.py`:
- Around line 114-117: reset_for_testing currently clears _TOKEN and _INSTALLED
but leaves any installed SIGINT wrapper active; modify the code so
reset_for_testing also restores the prior SIGINT handler by calling
signal.signal(signal.SIGINT, _PREV_SIGINT_HANDLER) (and then clear
_PREV_SIGINT_HANDLER), and ensure the SIGINT install path (the function that
sets up the wrapper) saves the original handler into a module-level variable
named _PREV_SIGINT_HANDLER when _INSTALLED is set; finally set _INSTALLED =
False and _TOKEN = None as before.
- Around line 80-84: get_token currently does a check-then-set on the global
_TOKEN without synchronization, which can create multiple CancellationToken
instances under concurrency; fix by guarding initialization with a module-level
lock (e.g., create _TOKEN_LOCK = threading.Lock()) and perform the assignment
inside the lock in get_token (use double-checked locking: check _TOKEN before
acquiring and re-check inside the lock) so only one CancellationToken is ever
created and returned by get_token.

In `@comfy_cli/cloud/command.py`:
- Around line 261-262: Remove the redundant re-import of ConfigManager from the
lower import block and instead import CONFIG_KEY_BASE_URL alongside the other
top-level imports; specifically, delete the second "from
comfy_cli.config_manager import ConfigManager" and add "from comfy_cli.cloud
import CONFIG_KEY_BASE_URL" (or move that symbol into the existing top import
group) near the other module imports so ConfigManager remains imported only once
and CONFIG_KEY_BASE_URL is consistently placed with top-level imports.

In `@comfy_cli/cloud/oauth.py`:
- Around line 243-250: The response-writing block in the OAuth HTTP handler
currently sets capture.received_event only after self.wfile.write succeeds, so a
broken socket can leave waiters blocked; wrap the send_header/end_headers and
wfile.write sequence in try/finally and call capture.received_event.set() from
the finally block (while keeping the write inside try and preserving any error
logging/handling) so that capture.received_event is signalled regardless of
write failures; update the method that contains
payload/self.send_header/self.wfile.write to move capture.received_event.set()
into the finally.
- Around line 418-430: Instead of pre-picking a port with _pick_free_port(),
create the HTTPServer bound to port 0 to let the OS assign an available port
(i.e., server = HTTPServer((_LOOPBACK_HOST, 0), handler_cls)), then read the
actual port from server.server_address[1] and construct redirect_uri using that
port; remove the TOCTOU usage of _pick_free_port(), keep constructing capture
via _CallbackCapture() and handler_cls via _build_handler(expected_state=state,
...), and ensure server.socket.setsockopt(...) and server_thread =
threading.Thread(target=server.handle_request, daemon=True) remain after server
creation so the socket option and thread use the actual bound socket.

In `@comfy_cli/command/__init__.py`:
- Around line 16-31: The package __init__.py currently eagerly re-exports many
submodules but omits the newly added project subcommand, which can cause
import-time failures; update both import tuples in comfy_cli.command.__init__
(the existing from . import (...) blocks that list code_search, custom_nodes,
generate, … and the second similar block) to include project so the project
module is eagerly imported and the anti-flake contract is preserved (i.e., add
the symbol "project" to the module import lists alongside the other subcommands
like run_cli, templates, transfer, workflow).

In `@comfy_cli/command/generate/app.py`:
- Around line 234-243: emit.write_workflow can raise OSError which is currently
uncaught; update the try/except around emit.write_workflow (the block that
currently catches emit.EmitError) to also catch OSError, call
_track_error("emit", e), call renderer.error with an appropriate code (e.g.,
"emit_write_failed" or reuse "emit_workflow_failed"), message=str(e) and a hint
about filesystem issues (permissions, readonly FS, invalid path), and then raise
typer.Exit(code=1) from the exception so filesystem write failures are surfaced
to the user in the same structured way as emit.EmitError.

In `@comfy_cli/command/generate/emit.py`:
- Around line 178-190: The code writes list-valued image params directly into
the LoadImage node (raw -> str(raw)), producing invalid pseudo-paths; fix by
detecting list/tuple values from ns.image_params (raw), fail-fast or extract a
single Path: if raw is a sequence, if empty raise a ValueError mentioning the
flag/node_key, otherwise set raw = raw[0] (or convert to Path) before computing
path = str(raw) and creating the loader node; ensure the loader creation code
(loader_id, workflow[...] "class_type": "LoadImage", node_inputs[node_key]) uses
the sanitized single-path string so Path(path).name remains valid.

In `@comfy_cli/command/jobs.py`:
- Around line 267-271: sort_key currently returns the raw ISO updated_at so
terminal jobs end up oldest-first; change sort_key (and leave sorted(...,
reverse=False)) so terminal rows produce a value that sorts newest-first — e.g.
parse r.updated_at to a datetime/epoch and for terminal jobs return the negated
epoch (or otherwise invert the timestamp) as the second tuple element, while
non-terminal rows keep a value that preserves their relative order; update the
sort_key implementation in the sort_key function used by ls_cmd() to use parsed
timestamps (datetime.fromisoformat or similar) and negation for terminal jobs so
slicing returns the freshest completed jobs.
- Around line 76-84: The returned host from _resolve_host_port needs IPv6
bracketting to produce valid URLs; update _resolve_host_port to, after computing
h (and after calling _validate_host if kept), wrap h in [ ] when it contains a
':' and is not already enclosed (e.g. detect if h.startswith('[') and
h.endswith(']') before adding brackets) so callers formatting
"http://{host}:{port}" or "ws://{host}:{port}" get a valid literal; keep
DEFAULT_HOST and DEFAULT_PORT usage and return the validated/bracketed host
along with int(port).
- Around line 793-805: The code currently always posts to /interrupt after
deleting from /queue; change it so /interrupt is only called when the prompt
being canceled is actually the running one by first GETting from
f"{base}/queue_running", parsing the returned running prompt id(s), and
comparing to prompt_id; only construct/post interrupt_req if prompt_id is
present in the /queue_running response, otherwise skip the interrupt (leaving
the existing queue deletion logic intact). Use the existing symbols (prompt_id,
base, interrupt_req) and reuse the same error handling for the interrupt POST
when performed.

In `@comfy_cli/command/models/search.py`:
- Around line 533-556: The current search builds qs with "limit=50" and only
calls _http_get_json once, so the client-side exact-name check over candidates
can miss matches beyond the first page; modify the logic around
qs/url/_http_get_json to paginate (e.g., loop with an offset/page parameter or
repeatedly request next pages until no more assets) and perform the exact match
check (on a.get("name") and a.get("display_name")) across all returned pages
before concluding match is None, breaking early when an exact match is found and
keeping the existing error handling for HTTP/URL/JSON errors.

In `@comfy_cli/command/nodes.py`:
- Around line 37-47: The _resolved_where helper should use the same defensive
routing fallback as comfy_cli.target.resolve_target(): replace the direct call
to where_module.resolve with a call to comfy_cli.target.resolve_target (or wrap
the where_module.resolve call in the same try/except logic) so config-read
failures and invalid config values are caught and a safe default is returned;
keep references to where_module.CONFIG_KEY_WHERE_DEFAULT and ensure the function
still returns the final target string (the equivalent of decision.target.value)
after applying the safe fallback.

In `@comfy_cli/command/project.py`:
- Around line 208-213: The asset-walking loop currently only checks
path.is_file(), which allows symlinks to files outside assets/ to be treated as
assets; update the logic in the loop that iterates assets_dir.rglob("*") (and
the similar block at 305-310) to skip symlinks and to verify the resolved target
remains inside the assets directory: require path.is_file() and not
path.is_symlink(), then compute resolved = path.resolve() and ensure resolved is
under assets_dir.resolve() (e.g., by attempting
resolved.relative_to(assets_dir.resolve()) or checking string-prefix), and
continue (skip) if that check fails so no external file is hashed/uploaded/read.
- Line 215: The code currently computes file SHA-256 by calling
path.read_bytes() (seen where variable sha is assigned), which loads the entire
file into memory; change this to stream the file in fixed-size chunks: open path
in binary mode, create a hashlib.sha256() object, loop reading e.g. 64KB chunks
and call hasher.update(chunk) until EOF, then call hasher.hexdigest(); replace
both occurrences (the assignment at the sha variable around line 215 and the
similar use at line 312) so no large file is fully loaded into memory.

In `@comfy_cli/command/run_cli.py`:
- Line 246: The _fleet_step function currently accepts pause_seconds but never
uses it; update _fleet_step (or document intentional omission) so it honors the
pause like other step handlers: add a sleep using pause_seconds at an
appropriate point (e.g., between queue snapshots or before returning) and ensure
time.sleep is imported/available, or if the omission is intentional, add a brief
comment explaining why pause_seconds is ignored to avoid confusion. Include
references to the _fleet_step function name when making the change so reviewers
can find the modification easily.

In `@comfy_cli/command/run/__init__.py`:
- Line 485: The execute_cloud function currently accepts a verbose: bool
parameter that is unused; either remove this parameter from execute_cloud's
signature (and update any callers) or wire it into the cloud execution path by
passing it into the cloud runner/logging code (e.g., into start/dispatch
functions or a logger configuration) so it actually toggles extra logging;
locate the execute_cloud function and adjust the signature and its callsites OR
propagate verbose into the relevant cloud execution/logging helpers to enable
verbose output.
- Around line 117-119: The host validation currently checks characters in the
frozenset _unsafe but omits the colon, allowing hosts like
"evil:8080@attacker.com" to pass and break the f"http://{host}:{port}/..." URL
construction; update the validation in the host-checking logic to include ":"
(add ":" to _unsafe) or replace the check with a stricter validation that
rejects any scheme/authority separators (e.g., ensure host contains no ":", "@",
"/", "?", "#" characters) so the code paths using host and port (referencing the
host variable and _unsafe set in this module) cannot be mangled by userinfo
fragments or embedded ports.

In `@comfy_cli/command/run/execution.py`:
- Line 82: WorkflowExecution currently accepts a local_paths parameter that is
never used; either remove the parameter from WorkflowExecution (and from its
caller in __init__.py) or wire it into the output path logic so it affects
format_image_path behavior—specifically, update the WorkflowExecution
constructor to drop local_paths (and update any instantiation sites) or store
local_paths on the instance and modify format_image_path (and any code that
formats output images) to consult self.local_paths when computing paths. Ensure
the change is reflected in the caller in __init__.py to avoid mismatched
signatures.

In `@comfy_cli/command/run/preflight.py`:
- Line 77: The function _preflight_validate declares a unused kwarg
target_label; either remove the parameter from _preflight_validate's signature
or incorporate it into the function's error reporting. Update the function
signature and all callers if you remove the param, or if keeping it, modify the
validation error message (e.g., when reporting "Workflow has {len(errors)}
validation error(s)" include the {target_label} value) so the parameter is
actually referenced; ensure any tests or call sites that pass target_label still
match the new signature/behavior.
- Around line 114-121: The timeout parameter on _fetch_object_info is declared
but never forwarded to _load_from_target; update _fetch_object_info to pass
timeout through to _load_from_target (e.g., _load_from_target(...,
timeout=timeout)) if _load_from_target supports it, otherwise remove the unused
timeout parameter from _fetch_object_info's signature and all callers; locate
the function by name _fetch_object_info and the callee _load_from_target to make
the change.

In `@comfy_cli/command/transfer.py`:
- Around line 419-426: Update the except block to preserve traceback by binding
the caught Unauthenticated exception and chaining it into the new exception:
change "except Unauthenticated:" to "except Unauthenticated as e:" and then
after calling renderer.error(...), raise the typer.Exit using explicit chaining
(raise typer.Exit(code=1) from e) so the original Unauthenticated is included in
the traceback; adjust references to prompt_id and renderer as needed in the
existing block.

In `@comfy_cli/command/workflow_fragments.py`:
- Around line 72-76: Wrap file I/O operations that can raise OSError/TypeError
(e.g., blueprint.read_text(encoding="utf-8"), base_out.unlink(), and any
write_text(...) calls referenced around the blueprint parsing and the later
block at lines ~141-156) in try/except that catches OSError and TypeError, call
renderer.error(...) with an appropriate code (e.g., "blueprint_io_error") and a
clear message including the exception, then raise typer.Exit(code=1) from the
caught exception so the CLI exits via the structured error envelope; update the
exception handling adjacent to the existing yaml.YAMLError block (where
blueprint_data is created) and the later file-delete/write sections to follow
the same pattern using renderer.error and typer.Exit.

In `@comfy_cli/cql/engine.py`:
- Around line 1472-1475: The current use of _resolve_node_path only forks the
first-hop definition, so deeper nested paths (e.g., A/B/C.input) can still
mutate interior shared nodes and leak state; update _resolve_node_path to
perform recursive isolation during traversal: for each segment visited (each
intermediate node id resolved from segments), detect if the node is shared
(appears in multiple parents or defs_by_id references), clone/duplicate that
node instance, replace the parent's reference to the cloned node and update
defs_by_id accordingly, then continue traversal into the cloned node so that
every hop along the path is isolated before the final write; ensure the function
updates any parent/child links and preserves node identities where not shared.
- Around line 1077-1083: The current loopback guard in the block guarded by
target.is_cloud uses parsed_host.startswith("127.") which can be spoofed by DNS
names like "127.0.0.1.evil.tld"; update the check to treat only actual IP
loopback addresses as allowed by parsing parsed_host with the ipaddress module
(handle both IPv4 and IPv6) and only permit when
ipaddress.ip_address(parsed_host).is_loopback is True; if parsed_host is not a
valid IP (ValueError) treat it as non-loopback and raise the same LoadError
(keep the existing urllib.parse.urlsplit(url).hostname usage and the same
LoadError path so non-IP hostnames like "127.x.evil" are rejected).
- Around line 942-943: Graph.load currently calls cls.from_object_info(raw)
without ensuring raw is a dict, so if the JSON root is a list (or other type)
from_object_info crashes when using .items(); add an explicit shape check and
raise the module's LoadError when invalid: before calling from_object_info (or
inside from_object_info at its start) verify isinstance(raw, dict), and if not
raise LoadError("invalid object_info: expected mapping/dict, got
{type(raw).__name__}") so callers get a proper LoadError contract instead of an
AttributeError; update Graph.load() to use this validated path.
- Around line 627-631: The current verification in exact_paths() is always true
because available is seeded with from_type, so the predicate
"any(s['input_type'] == from_type or from_type in available for s in new_steps)"
will pass even when no step actually consumes from_type; change the check to
assert that at least one step in new_steps directly consumes the source by using
"any(s['input_type'] == from_type for s in new_steps)" or, if you meant to allow
indirect consumption, compute the set of consumed types from the steps (e.g.,
consumed = {s['input_type'] for s in new_steps}) and test "from_type in
consumed"; update the condition that appends paths to use that corrected
predicate (referencing exact_paths, from_type, available, new_steps).

In `@comfy_cli/cql/errors.py`:
- Around line 28-29: The current as_details method merges self.details after
setting "runtime_message", allowing details["runtime_message"] to override the
canonical message; modify as_details so the canonical runtime_message wins by
merging details first and then setting "runtime_message" (i.e., ensure
"runtime_message" is last in the dict), or alternatively filter out any
"runtime_message" key from self.details before merging; update the as_details
method accordingly (referencing as_details, self.runtime_message, and
self.details).

In `@comfy_cli/cql/loader.py`:
- Around line 150-159: The shape detector _looks_like_object_info currently
stops after examining the first mapping value (it contains a stray break), which
causes misclassification when later entries contain the expected metadata;
remove the break and change the loop to inspect every value so it returns True
if any value is a dict containing "input" or "category" and returns False only
after checking all values; apply the same fix to the other analogous detector in
this module that uses the same early-break pattern so both functions fully scan
all entries.
- Around line 248-257: The code marks any 2-item list as a reference (ref)
causing numeric pairs like [1024, 1024] to be misparsed; change the detection
logic used when building the dict in inputs.append so ref is true only when the
second element looks like a slot identifier (e.g. isinstance(value[1], str)) —
update the computation of ref and the subsequent use of
ref_node/ref_slot/is_reference in that block (the variables ref, ref_node,
ref_slot inside the inputs.append call) so only legitimate [node, slot] pairs
are treated as references.
- Around line 97-101: The current check using host.startswith("127.") is
bypassable (e.g., "127.0.0.1.evil.com"); replace this with a robust loopback
check by using parsed.hostname and Python's ipaddress module (or
socket/inet_aton) to determine if the hostname is a loopback IP: call
ipaddress.ip_address(parsed.hostname).is_loopback (after handling exceptions for
non-IP hostnames) and allow "localhost" / "::1" explicitly; if the hostname is
not a loopback according to this check, raise the same CQLRuntimeError with the
existing details. Ensure you reference parsed.hostname and remove the brittle
host.startswith("127.") check and handle ValueError when parsed.hostname is not
an IP.

In `@comfy_cli/fragments.py`:
- Around line 805-817: The foreach item keys produced by _item_key (and used by
_item_prefix and the item_map) can collide when different items share the same
id; add a validation step before building item_map and generating prefixes (the
code that iterates items to create item_map and call _item_prefix) that computes
keys via _item_key for all items, detects duplicates, and raises a clear
exception (e.g., ValueError) listing the duplicated key(s) and their item
indices so the caller can fix input; apply the same check in the other affected
block that constructs per-item mappings (the code around the alternative
implementation at lines 872–885) to prevent silent overwrites and prefix
collisions.
- Around line 215-220: The code currently converts port values with direct
int(...) calls (e.g., the line setting port.port = int(spec.get("port", 0)) and
occurrences of int(old)) which can raise ValueError outside the FragmentError
path; update the parse-stage logic in comfy_cli/fragments.py to validate and
normalize node IDs and numeric ports rather than letting compose handle them:
replace direct int() calls with a small try/except that catches ValueError and
raises FragmentError with a clear message referencing the fragment
name/port/node id, and ensure the same validation is added for the other
occurrences noted (around the blocks at ~267-276 and ~536-538) so malformed
numeric ports and node ids are converted or rejected during parse-time.
- Around line 314-320: resolve_fragment_name incorrectly appends ".json" even
when the provided name already ends with ".json", producing "<name>.json.json";
update the logic in resolve_fragment_name to check the raw input (or
candidate.name) for a ".json" suffix and only append ".json" when it's missing,
while preserving the existing early-return when candidate.is_file() succeeds and
keeping the final return as a Path under lib_dir with expanduser applied (use
the function name resolve_fragment_name and variables candidate and lib_dir to
locate the code to change).
- Around line 245-250: The code currently uses meta.get("inputs") or {} (and
same for "outputs"/"params"), which silently converts falsy non-dict values
(e.g. [] or "") into {} and hides schema errors; change the retrieval to only
provide an empty dict when the key is absent (use "if 'inputs' in meta then
meta.get('inputs') else {}" pattern for "inputs", "outputs", "params") and keep
the existing isinstance(...) checks so that non-dict but present values raise
FragmentError (reference: variables inputs_raw/outputs_raw/params_raw and the
FragmentError raised).

In `@comfy_cli/jobs_state.py`:
- Around line 141-155: The read function can raise TypeError when constructing
JobState from filtered data missing required fields; update the
JobState(**filtered) call in read(prompt_id: str) to be inside a try/except that
catches TypeError (and optionally ValueError) and returns None on failure so
malformed state files are treated as absent; keep the existing tolerant
filtering logic and only change the constructor call to handle and swallow
construction errors gracefully.

In `@comfy_cli/locking.py`:
- Around line 102-115: The _acquire function uses msvcrt.locking which locks
from the current file position; to mirror _release and avoid drift, seek the
file descriptor to offset 0 before calling msvcrt.locking — update the
_acquire(fd: int, *, timeout: float | None) implementation to perform an
explicit os.lseek(fd, 0, os.SEEK_SET) (or equivalent) prior to the locking
attempts so both _acquire and _release operate on byte 0 consistently.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6ba141f4-f960-4949-8955-776638a71c02

📥 Commits

Reviewing files that changed from the base of the PR and between 74a8241 and 7db86c0.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (175)

• .github/workflows/ruff_check.yml
• .gitignore
• .pre-commit-config.yaml
• README.md
• comfy_cli/auth/__init__.py
• comfy_cli/auth/command.py
• comfy_cli/auth/store.py
• comfy_cli/caller.py
• comfy_cli/cancellation.py
• comfy_cli/cloud/__init__.py
• comfy_cli/cloud/command.py
• comfy_cli/cloud/oauth.py
• comfy_cli/cmdline.py
• comfy_cli/comfy_client.py
• comfy_cli/command/__init__.py
• comfy_cli/command/custom_nodes/cm_cli_util.py
• comfy_cli/command/custom_nodes/command.py
• comfy_cli/command/generate/app.py
• comfy_cli/command/generate/client.py
• comfy_cli/command/generate/emit.py
• comfy_cli/command/generate/output.py
• comfy_cli/command/generate/schema.py
• comfy_cli/command/generate/spec.py
• comfy_cli/command/install.py
• comfy_cli/command/job_watcher.py
• comfy_cli/command/jobs.py
• comfy_cli/command/launch.py
• comfy_cli/command/models/models.py
• comfy_cli/command/models/search.py
• comfy_cli/command/nodes.py
• comfy_cli/command/project.py
• comfy_cli/command/run.py
• comfy_cli/command/run/__init__.py
• comfy_cli/command/run/credentials.py
• comfy_cli/command/run/execution.py
• comfy_cli/command/run/loader.py
• comfy_cli/command/run/preflight.py
• comfy_cli/command/run/watcher.py
• comfy_cli/command/run_cli.py
• comfy_cli/command/setup.py
• comfy_cli/command/templates.py
• comfy_cli/command/transfer.py
• comfy_cli/command/workflow.py
• comfy_cli/command/workflow_fragments.py
• comfy_cli/config_manager.py
• comfy_cli/constants.py
• comfy_cli/cql/__init__.py
• comfy_cli/cql/data/__init__.py
• comfy_cli/cql/data/cloud_disable_config.yaml
• comfy_cli/cql/data/no_gpu_nodes.json
• comfy_cli/cql/data/supported_nodes.yaml
• comfy_cli/cql/engine.py
• comfy_cli/cql/errors.py
• comfy_cli/cql/loader.py
• comfy_cli/credentials.py
• comfy_cli/discovery.py
• comfy_cli/env_checker.py
• comfy_cli/error_codes.py
• comfy_cli/execution_errors.py
• comfy_cli/fragments.py
• comfy_cli/help_json.py
• comfy_cli/jobs_state.py
• comfy_cli/locking.py
• comfy_cli/output/__init__.py
• comfy_cli/output/branding.py
• comfy_cli/output/glyphs.py
• comfy_cli/output/panels.py
• comfy_cli/output/preview.py
• comfy_cli/output/renderer.py
• comfy_cli/output/rich_compat.py
• comfy_cli/project.py
• comfy_cli/schemas/__init__.py
• comfy_cli/schemas/assets.json
• comfy_cli/schemas/auth.json
• comfy_cli/schemas/discover.json
• comfy_cli/schemas/env.json
• comfy_cli/schemas/envelope.json
• comfy_cli/schemas/error.json
• comfy_cli/schemas/error_codes.md
• comfy_cli/schemas/help.json
• comfy_cli/schemas/jobs.json
• comfy_cli/schemas/models.json
• comfy_cli/schemas/nodes.json
• comfy_cli/schemas/project.json
• comfy_cli/schemas/run.json
• comfy_cli/schemas/run_event.json
• comfy_cli/schemas/set_default.json
• comfy_cli/schemas/skill.json
• comfy_cli/schemas/templates.json
• comfy_cli/schemas/transfer.json
• comfy_cli/schemas/version.json
• comfy_cli/schemas/which.json
• comfy_cli/schemas/workflow.json
• comfy_cli/skills/__init__.py
• comfy_cli/skills/comfy-debug/SKILL.md
• comfy_cli/skills/comfy-director/SKILL.md
• comfy_cli/skills/comfy-fragments/SKILL.md
• comfy_cli/skills/comfy-relay/SKILL.md
• comfy_cli/skills/comfy/SKILL.md
• comfy_cli/skills/comfy/__init__.py
• comfy_cli/skills/command.py
• comfy_cli/target.py
• comfy_cli/tracking.py
• comfy_cli/update.py
• comfy_cli/utils.py
• comfy_cli/where.py
• comfy_cli/workspace_manager.py
• docs/json-output.md
• pyproject.toml
• scripts/verify_tracking_live.py
• tests/comfy_cli/auth/__init__.py
• tests/comfy_cli/auth/test_auth_command.py
• tests/comfy_cli/auth/test_oauth.py
• tests/comfy_cli/auth/test_store.py
• tests/comfy_cli/auth/test_where.py
• tests/comfy_cli/cloud/__init__.py
• tests/comfy_cli/cloud/test_client.py
• tests/comfy_cli/command/generate/test_app.py
• tests/comfy_cli/command/generate/test_client.py
• tests/comfy_cli/command/generate/test_emit.py
• tests/comfy_cli/command/github/test_pr.py
• tests/comfy_cli/command/models/test_search.py
• tests/comfy_cli/command/test_asset_refs.py
• tests/comfy_cli/command/test_assets_push.py
• tests/comfy_cli/command/test_command.py
• tests/comfy_cli/command/test_command_init.py
• tests/comfy_cli/command/test_manager_gui.py
• tests/comfy_cli/command/test_nodes_cli.py
• tests/comfy_cli/command/test_nodes_introspect.py
• tests/comfy_cli/command/test_observer_session_safety.py
• tests/comfy_cli/command/test_project_command.py
• tests/comfy_cli/command/test_run.py
• tests/comfy_cli/command/test_run_cli.py
• tests/comfy_cli/command/test_run_json.py
• tests/comfy_cli/command/test_setup_consent.py
• tests/comfy_cli/command/test_templates.py
• tests/comfy_cli/command/test_transfer_download.py
• tests/comfy_cli/command/test_transfer_redirect.py
• tests/comfy_cli/command/test_transfer_upload.py
• tests/comfy_cli/command/test_var_refs.py
• tests/comfy_cli/command/test_workflow_fragments.py
• tests/comfy_cli/command/test_workflow_saved.py
• tests/comfy_cli/command/test_workflow_slots.py
• tests/comfy_cli/conftest.py
• tests/comfy_cli/cql/__init__.py
• tests/comfy_cli/cql/test_engine.py
• tests/comfy_cli/cql/test_loader.py
• tests/comfy_cli/cql/test_loader_resilient.py
• tests/comfy_cli/fixtures/subgraph_object_info.json
• tests/comfy_cli/fixtures/subgraph_template_ui.json
• tests/comfy_cli/jobs/__init__.py
• tests/comfy_cli/jobs/test_jobs.py
• tests/comfy_cli/output/__init__.py
• tests/comfy_cli/output/test_branding.py
• tests/comfy_cli/output/test_caller.py
• tests/comfy_cli/output/test_cancellation.py
• tests/comfy_cli/output/test_discovery.py
• tests/comfy_cli/output/test_envelope_schemas.py
• tests/comfy_cli/output/test_error_code_registry.py
• tests/comfy_cli/output/test_glyphs.py
• tests/comfy_cli/output/test_help_json.py
• tests/comfy_cli/output/test_locking.py
• tests/comfy_cli/output/test_panels.py
• tests/comfy_cli/output/test_renderer.py
• tests/comfy_cli/skills/__init__.py
• tests/comfy_cli/skills/test_installer.py
• tests/comfy_cli/test_credentials.py
• tests/comfy_cli/test_execution_errors.py
• tests/comfy_cli/test_feedback_commands.py
• tests/comfy_cli/test_jobs_state.py
• tests/comfy_cli/test_launch_python_resolution.py
• tests/comfy_cli/test_project.py
• tests/comfy_cli/test_run_execution_lifecycle.py
• tests/comfy_cli/test_tracking.py
• tests/comfy_cli/test_update.py

💤 Files with no reviewable changes (1)

• comfy_cli/command/run.py

[coderabbitai]

🧹 Nitpick | 🔵 Trivial | 💤 Low value

Consider renaming set to avoid shadowing the built-in.

The function name set shadows Python's built-in set type. While this is a common pattern for store APIs, it can cause confusion if someone tries to use the built-in within this module. A name like store or upsert would be clearer and less prone to trip you up.

🧰 Tools

🪛 Pylint (4.0.5)

[warning] 187-187: Redefining built-in 'set'

(W0622)

---

[convention] 187-187: Missing function or method docstring

(C0116)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@comfy_cli/auth/store.py` around lines 187 - 200, The function name set
shadows Python's built-in set; rename the function to a clearer name (e.g.,
store or upsert) by renaming the definition def set(...) to def store(...) (or
def upsert(...)) and update all internal references and exports accordingly (any
call sites in this module, imports elsewhere, and __all__ if present) so callers
use the new name; keep the implementation logic and signature the same and add a
short compatibility shim (optional) that forwards the old name to the new
function if you need back-compatibility.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	jsonschema@​4.26.0
	term-image@​0.7.2
	uv@​0.11.6 ⏵ 0.11.20		+2

View full report

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

comfy_cli/tracking.py (1)

194-204: ⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

Critical: disable() command enables tracking instead of disabling it, and enable() duplicates its initialization call.

Line 203 invokes init_tracking(True) but should invoke init_tracking(False). This breaks the disable command—users cannot opt out of tracking via the CLI. Line 198 in enable() redundantly calls init_tracking(True) again.

Additionally, the f-string literals in lines 197 and 204 use unnecessary f-string syntax without variable interpolation.

🔧 Proposed fix for both command functions

 `@app.command`()
 def enable():
     init_tracking(True)
-    typer.echo(f"Tracking is now {'enabled'}.")
-    init_tracking(True)
+    typer.echo("Tracking is now enabled.")

 `@app.command`()
 def disable():
-    init_tracking(False)
-    typer.echo(f"Tracking is now {'disabled'}.")
+    init_tracking(False)
+    typer.echo("Tracking is now disabled.")

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@comfy_cli/tracking.py` around lines 194 - 204, The disable() command
incorrectly calls init_tracking(True) and enable() calls init_tracking(True)
twice and both echo strings use unnecessary f-strings; update enable() to call
init_tracking(True) only once (remove the duplicate init_tracking(True)), update
disable() to call init_tracking(False) instead of True, and simplify the echo
messages in both enable() and disable() (use plain string literals rather than
f-strings) while keeping the function names enable and disable and the
init_tracking and typer.echo calls intact.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@comfy_cli/tracking.py`:
- Around line 194-204: The disable() command incorrectly calls
init_tracking(True) and enable() calls init_tracking(True) twice and both echo
strings use unnecessary f-strings; update enable() to call init_tracking(True)
only once (remove the duplicate init_tracking(True)), update disable() to call
init_tracking(False) instead of True, and simplify the echo messages in both
enable() and disable() (use plain string literals rather than f-strings) while
keeping the function names enable and disable and the init_tracking and
typer.echo calls intact.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: d096bb3d-4186-4bf9-aff6-61de38a575e8

📥 Commits

Reviewing files that changed from the base of the PR and between 7db86c0 and 2530aed.

📒 Files selected for processing (3)

• comfy_cli/command/custom_nodes/command.py
• comfy_cli/tracking.py
• tests/comfy_cli/test_tracking.py

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

tests/comfy_cli/command/test_manager_gui.py (2)

82-86: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick win

Loose assertion on captured output may mask behavior mismatches.

Line 86 asserts that the captured output contains either "unknown-mode" (lowercased) or the literal string "Unknown manager mode". This disjunctive assertion is permissive and could hide cases where the actual output differs from both expectations—for example, if the implementation emits a warning with different wording or casing.

Consider checking the actual implementation of _get_manager_flags() and tightening the assertion to match exactly what the code produces.

💡 Tighten the assertion (draft)

Once you've confirmed the exact output string from the implementation:

-        assert "unknown-mode" in captured.out.lower() or "Unknown manager mode" in captured.out
+        assert "Unknown manager mode: unknown-mode" in captured.out

(Adjust the expected string based on the actual implementation output.)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/comfy_cli/command/test_manager_gui.py` around lines 82 - 86, The test
test_unknown_mode_returns_default_with_warning uses a loose disjunctive
assertion on captured output which can mask mismatches; open the implementation
of _get_manager_flags(), determine the exact warning string it emits for an
unknown mode (exact text and casing), then replace the current or-check in the
assertion with a precise check that matches that exact string (e.g., assert
expected_msg in captured.out or assert captured.out.strip() == expected_msg)
inside test_unknown_mode_returns_default_with_warning so the test fails if the
wording or casing changes.

---

1091-1115: 🧹 Nitpick | 🔵 Trivial | 💤 Low value

Test structure is sound, but consider cache-clearing robustness.

The test test_find_cm_cli_cache_behavior at lines 1091–1115 correctly verifies that find_cm_cli() caches results after the first call. However, calling cache_clear() at line 1102 inside the test method (after already patching and importing the function) assumes that cache_clear() is always available on the imported function. If the function implementation or import order changes, this could become fragile.

A minor refinement: ensure cache_clear() is explicitly verified to exist (or gracefully handle its absence) before relying on it in all tests that use it.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/comfy_cli/command/test_manager_gui.py` around lines 1091 - 1115, The
test assumes find_cm_cli has a cache_clear attribute; make the test robust by
checking for and calling it only if present: after importing find_cm_cli in
test_find_cm_cli_cache_behavior, verify hasattr(find_cm_cli, "cache_clear") (or
use getattr with default None) and call cache_clear() only when available,
otherwise proceed without error; this ensures the test won't fail if find_cm_cli
loses or changes its lru_cache decoration while preserving the rest of the
assertions.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@tests/comfy_cli/command/test_manager_gui.py`:
- Around line 82-86: The test test_unknown_mode_returns_default_with_warning
uses a loose disjunctive assertion on captured output which can mask mismatches;
open the implementation of _get_manager_flags(), determine the exact warning
string it emits for an unknown mode (exact text and casing), then replace the
current or-check in the assertion with a precise check that matches that exact
string (e.g., assert expected_msg in captured.out or assert captured.out.strip()
== expected_msg) inside test_unknown_mode_returns_default_with_warning so the
test fails if the wording or casing changes.
- Around line 1091-1115: The test assumes find_cm_cli has a cache_clear
attribute; make the test robust by checking for and calling it only if present:
after importing find_cm_cli in test_find_cm_cli_cache_behavior, verify
hasattr(find_cm_cli, "cache_clear") (or use getattr with default None) and call
cache_clear() only when available, otherwise proceed without error; this ensures
the test won't fail if find_cm_cli loses or changes its lru_cache decoration
while preserving the rest of the assertions.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6a12dbbd-5940-48fc-94a6-f34181cdd37b

📥 Commits

Reviewing files that changed from the base of the PR and between 7b4fec3 and 509554e.

📒 Files selected for processing (3)

• comfy_cli/help_json.py
• tests/comfy_cli/command/github/test_pr.py
• tests/comfy_cli/command/test_manager_gui.py

[codecov]

Codecov Report

❌ Patch coverage is 70.47091% with 2132 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
comfy_cli/command/jobs.py	51.08%	338 Missing ⚠️
comfy_cli/command/setup.py	15.69%	247 Missing ⚠️
comfy_cli/command/nodes.py	47.49%	178 Missing ⚠️
comfy_cli/cmdline.py	33.99%	167 Missing ⚠️
comfy_cli/cql/engine.py	81.44%	152 Missing ⚠️
comfy_cli/cloud/command.py	18.49%	119 Missing ⚠️
comfy_cli/command/workflow.py	69.29%	105 Missing ⚠️
comfy_cli/command/models/search.py	68.00%	80 Missing ⚠️
comfy_cli/command/run/__init__.py	78.77%	76 Missing ⚠️
comfy_cli/command/project.py	61.62%	66 Missing ⚠️
... and 30 more

@@            Coverage Diff             @@
##             main     #470      +/-   ##
==========================================
- Coverage   83.36%   76.55%   -6.82%     
==========================================
  Files          45       95      +50     
  Lines        6848    14793    +7945     
==========================================
+ Hits         5709    11325    +5616     
- Misses       1139     3468    +2329     

Files with missing lines	Coverage Δ
comfy_cli/auth/__init__.py	100.00% <100.00%> (ø)
comfy_cli/caller.py	100.00% <100.00%> (ø)
comfy_cli/command/__init__.py	100.00% <100.00%> (ø)
comfy_cli/command/custom_nodes/cm_cli_util.py	95.49% <100.00%> (+0.08%)	⬆️
comfy_cli/command/generate/client.py	77.77% <100.00%> (-0.49%)	⬇️
comfy_cli/command/generate/output.py	92.10% <100.00%> (+0.32%)	⬆️
comfy_cli/command/generate/schema.py	81.33% <100.00%> (+0.12%)	⬆️
comfy_cli/command/generate/spec.py	91.08% <ø> (ø)
comfy_cli/command/install.py	81.67% <100.00%> (ø)
comfy_cli/command/models/models.py	72.91% <100.00%> (ø)
... and 60 more

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.