arctx-cli 0.2.0b4__tar.gz → 0.3.1b1__tar.gz

{arctx_cli-0.2.0b4 → arctx_cli-0.3.1b1}/.gitignore

@@ -5,6 +5,8 @@ __pycache__/
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/
+.uv-cache/
+.venv/
 .coverage
 htmlcov/
 
@@ -27,4 +29,5 @@ dist/
 # IDE / Agent state directories
 .claude/
 .antigravitycli/
+.codex/
 

{arctx_cli-0.2.0b4 → arctx_cli-0.3.1b1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: arctx-cli
-Version: 0.2.0b4
-Summary: CLI for ARCTX — append-only DAG for reasoning history and parallel agent work
+Version: 0.3.1b1
+Summary: CLI for ARCTX — append-only DAG editing and refactoring
 Project-URL: Homepage, https://github.com/takumiecd/arctx
 Project-URL: Repository, https://github.com/takumiecd/arctx
 Author: Takumi Ishida
@@ -17,7 +17,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
 Requires-Python: >=3.10
-Requires-Dist: arctx>=0.2.0b4
+Requires-Dist: arctx>=0.3.1b1
 Provides-Extra: dev
 Requires-Dist: black>=23.0; extra == 'dev'
 Requires-Dist: mypy>=1.0; extra == 'dev'

{arctx_cli-0.2.0b4 → arctx_cli-0.3.1b1}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arctx-cli"
-version = "0.2.0b4"
-description = "CLI for ARCTX — append-only DAG for reasoning history and parallel agent work"
+version = "0.3.1b1"
+description = "CLI for ARCTX — append-only DAG editing and refactoring"
 readme = "README.md"
 requires-python = ">=3.10"
 license = {text = "MIT"}
@@ -25,7 +25,7 @@ classifiers = [
     "Topic :: Utilities",
 ]
 dependencies = [
-    "arctx>=0.2.0b4",
+    "arctx>=0.3.1b1",
 ]
 
 [project.optional-dependencies]

{arctx_cli-0.2.0b4 → arctx_cli-0.3.1b1}/src/arctx_cli/append_batch.py

@@ -9,9 +9,8 @@ def graph_counts(handle) -> dict[str, set[str]]:
     """Capture graph record IDs before a mutation."""
     return {
         "nodes": set(handle.run_graph.nodes),
-        "transitions": set(handle.run_graph.transitions),
+        "steps": set(handle.run_graph.steps),
         "payloads": set(handle.run_graph.payloads),
-        "views": {view.view_id for view in handle.run_graph.views.values()},
         "work_events": {event.event_id for event in handle.run_graph.work_events},
     }
 
@@ -21,18 +20,18 @@ def maybe_append_or_save(
     store,
     handle,
     user_id: str | None,
-    work_session_id: str | None,
+    lane_id: str | None,
     before: dict[str, set[str]],
 ) -> None:
     """Use append_batch for capable stores, otherwise fall back to save_run."""
-    if user_id is None or work_session_id is None or not hasattr(store, "append_batch"):
+    if user_id is None or lane_id is None or not hasattr(store, "append_batch"):
         store.save_run(handle)
         return
     store.append_batch(
         build_append_batch(
             handle,
             user_id=user_id,
-            work_session_id=work_session_id,
+            lane_id=lane_id,
             before=before,
         )
     )
@@ -42,7 +41,7 @@ def build_append_batch(
     handle,
     *,
     user_id: str,
-    work_session_id: str,
+    lane_id: str,
     before: dict[str, set[str]],
 ) -> AppendBatch:
     """Build an append batch from records added since *before*."""
@@ -52,21 +51,14 @@ def build_append_batch(
         node = handle.run_graph.nodes[node_id]
         records.append(GraphRecordEnvelope("node", node.node_id, node))
 
-    for transition_id in _new_ids(handle.run_graph.transitions, before, "transitions"):
-        transition = handle.run_graph.transitions[transition_id]
-        records.append(GraphRecordEnvelope("transition", transition.transition_id, transition))
+    for step_id in _new_ids(handle.run_graph.steps, before, "steps"):
+        step = handle.run_graph.steps[step_id]
+        records.append(GraphRecordEnvelope("step", step.step_id, step))
 
     for payload_id in _new_ids(handle.run_graph.payloads, before, "payloads"):
         payload = handle.run_graph.payloads[payload_id]
         records.append(GraphRecordEnvelope("payload", payload.payload_id, payload))
 
-    before_view_ids = before.get("views", set())
-    new_views = [
-        view for view in handle.run_graph.views.values() if view.view_id not in before_view_ids
-    ]
-    for view in new_views:
-        records.append(GraphRecordEnvelope("view", view.view_id, view))
-
     new_events = [
         event
         for event in handle.run_graph.work_events
@@ -75,12 +67,12 @@ def build_append_batch(
     if not new_events:
         raise RuntimeError("append batch requires at least one work event")
 
-    session = handle.run_graph.work_sessions[work_session_id]
+    session = handle.run_graph.lanes[lane_id]
     return AppendBatch(
         run_id=handle.run_id,
         user_id=user_id,
-        work_session_id=work_session_id,
-        work_session=session,
+        lane_id=lane_id,
+        lane=session,
         events=tuple(new_events),
         records=tuple(records),
     )

{arctx_cli-0.2.0b4 → arctx_cli-0.3.1b1}/src/arctx_cli/commands/__init__.py

@@ -7,10 +7,14 @@ from arctx.ext import CliCommand
 
 def core_cli_commands() -> list[CliCommand]:
     """Return the built-in, extension-independent CLI commands."""
+    from arctx_cli.commands.add import add_parser as add_add_parser
+    from arctx_cli.commands.add import cli_add
     from arctx_cli.commands.alias_cmd import add_parser as add_alias_parser
     from arctx_cli.commands.alias_cmd import cli_alias
-    from arctx_cli.commands.anchor import add_parser as add_anchor_parser
-    from arctx_cli.commands.anchor import cli_anchor
+    from arctx_cli.commands.asset import add_parser as add_asset_parser
+    from arctx_cli.commands.asset import cli_asset
+    from arctx_cli.commands.attach import add_parser as add_attach_parser
+    from arctx_cli.commands.attach import cli_attach
     from arctx_cli.commands.current import add_parser as add_current_parser
     from arctx_cli.commands.current import cli_current
     from arctx_cli.commands.cut import add_parser as add_cut_parser
@@ -27,36 +31,48 @@ def core_cli_commands() -> list[CliCommand]:
     from arctx_cli.commands.guide import cli_guide
     from arctx_cli.commands.init import add_parser as add_init_parser
     from arctx_cli.commands.init import cli_init
+    from arctx_cli.commands.lane import add_parser as add_lane_parser
+    from arctx_cli.commands.lane import cli_lane
     from arctx_cli.commands.list import add_parser as add_list_parser
     from arctx_cli.commands.list import cli_list
+    from arctx_cli.commands.log import add_parser as add_log_parser
+    from arctx_cli.commands.log import cli_log
     from arctx_cli.commands.migrate import add_parser as add_migrate_parser
     from arctx_cli.commands.migrate import cli_migrate
-    from arctx_cli.commands.node import add_parser as add_node_parser
-    from arctx_cli.commands.node import cli_node
-    from arctx_cli.commands.outcomes import add_parser as add_outcomes_parser
-    from arctx_cli.commands.outcomes import cli_outcomes
-    from arctx_cli.commands.payload import add_parser as add_payload_parser
-    from arctx_cli.commands.payload import cli_payload
-    from arctx_cli.commands.reachable import add_parser as add_reachable_parser
-    from arctx_cli.commands.reachable import cli_reachable
+    from arctx_cli.commands.reparent import add_parser as add_reparent_parser
+    from arctx_cli.commands.reparent import cli_reparent
+    from arctx_cli.commands.uncut import add_parser as add_uncut_parser
+    from arctx_cli.commands.uncut import cli_uncut
+    from arctx_cli.commands.pr import (
+        add_accept_parser,
+        add_propose_parser,
+        add_reject_parser,
+        cli_accept,
+        cli_propose,
+        cli_reject,
+    )
+    from arctx_cli.commands.serve import add_parser as add_serve_parser
+    from arctx_cli.commands.serve import cli_serve
+    from arctx_cli.commands.sync_cmd import (
+        add_pull_parser,
+        add_push_parser,
+        add_remote_parser,
+        cli_pull,
+        cli_push,
+        cli_remote,
+    )
     from arctx_cli.commands.show import add_parser as add_show_parser
     from arctx_cli.commands.show import cli_show
-    from arctx_cli.commands.sync import add_parser as add_sync_parser
-    from arctx_cli.commands.sync import cli_sync
-    from arctx_cli.commands.trace import add_parser as add_trace_parser
-    from arctx_cli.commands.trace import cli_trace
-    from arctx_cli.commands.transition import add_parser as add_transition_parser
-    from arctx_cli.commands.transition import cli_transition
     from arctx_cli.commands.use import add_parser as add_use_parser
     from arctx_cli.commands.use import cli_use
-    from arctx_cli.commands.view import add_parser as add_view_parser
-    from arctx_cli.commands.view import cli_view
-    from arctx_cli.commands.work_session import add_parser as add_work_session_parser
-    from arctx_cli.commands.work_session import cli_work_session
+    from arctx_cli.commands.web import add_parser as add_web_parser
+    from arctx_cli.commands.web import cli_web
 
     return [
+        CliCommand("add", add_add_parser, cli_add),
         CliCommand("alias", add_alias_parser, cli_alias),
-        CliCommand("anchor", add_anchor_parser, cli_anchor),
+        CliCommand("asset", add_asset_parser, cli_asset),
+        CliCommand("attach", add_attach_parser, cli_attach),
         CliCommand("current", add_current_parser, cli_current),
         CliCommand("ext", add_ext_parser, cli_ext),
         CliCommand("dump", add_dump_parser, cli_dump),
@@ -64,20 +80,22 @@ def core_cli_commands() -> list[CliCommand]:
         CliCommand("graph", add_graph_parser, cli_graph),
         CliCommand("guide", add_guide_parser, cli_guide),
         CliCommand("init", add_init_parser, cli_init),
+        CliCommand("lane", add_lane_parser, cli_lane),
         CliCommand("list", add_list_parser, cli_list),
+        CliCommand("log", add_log_parser, cli_log),
         CliCommand("migrate", add_migrate_parser, cli_migrate),
-        CliCommand("node", add_node_parser, cli_node),
-        CliCommand("outcomes", add_outcomes_parser, cli_outcomes),
-        CliCommand("payload", add_payload_parser, cli_payload),
-        CliCommand("reachable", add_reachable_parser, cli_reachable),
         CliCommand("cut", add_cut_parser, cli_cut),
+        CliCommand("uncut", add_uncut_parser, cli_uncut),
+        CliCommand("reparent", add_reparent_parser, cli_reparent),
+        CliCommand("propose", add_propose_parser, cli_propose),
+        CliCommand("accept", add_accept_parser, cli_accept),
+        CliCommand("reject", add_reject_parser, cli_reject),
+        CliCommand("remote", add_remote_parser, cli_remote),
+        CliCommand("push", add_push_parser, cli_push),
+        CliCommand("serve", add_serve_parser, cli_serve),
         CliCommand("show", add_show_parser, cli_show),
-        CliCommand("sync", add_sync_parser, cli_sync),
-        CliCommand("trace", add_trace_parser, cli_trace),
-        CliCommand("transition", add_transition_parser, cli_transition),
         CliCommand("use", add_use_parser, cli_use),
-        CliCommand("view", add_view_parser, cli_view),
-        CliCommand("work-session", add_work_session_parser, cli_work_session),
+        CliCommand("web", add_web_parser, cli_web),
     ]
 
 

arctx_cli-0.3.1b1/src/arctx_cli/commands/_targets.py

@@ -0,0 +1,38 @@
+"""Helpers for resolving user-facing DAG record IDs."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+
+TargetKind = Literal["node", "step", "payload"]
+
+
+def resolve_target_kind(handle, record_id: str) -> TargetKind:
+    """Resolve a record id to its internal target kind."""
+    graph = handle.run_graph
+    matches: list[TargetKind] = []
+    if record_id in graph.nodes:
+        matches.append("node")
+    if record_id in graph.steps:
+        matches.append("step")
+    if record_id in graph.payloads:
+        matches.append("payload")
+    if not matches:
+        raise KeyError(f"unknown record_id: {record_id}")
+    if len(matches) > 1:
+        raise ValueError(f"ambiguous record_id {record_id!r}: {matches}")
+    return matches[0]
+
+
+def step_view(step) -> dict:
+    """Return a user-facing Step view for an internal Step."""
+    return {
+        "kind": "step",
+        "id": step.step_id,
+        "step_id": step.step_id,
+        "step_id": step.step_id,
+        "input_node_ids": list(step.input_node_ids),
+        "output_node_id": step.output_node_id,
+        "metadata": dict(step.metadata),
+    }

arctx_cli-0.3.1b1/src/arctx_cli/commands/add.py

@@ -0,0 +1,113 @@
+"""User-facing arctx add commands."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from arctx_cli.append_batch import graph_counts, maybe_append_or_save
+from arctx_cli.commands._targets import step_view
+from arctx_cli.context import (
+    resolve_run_id_from_args,
+    resolve_store,
+    resolve_user_id_from_args,
+    resolve_lane_id_from_args,
+)
+from arctx_cli.payload_builder import build_payload, parse_field_args, parse_json_object
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser("add", help="Add a Step from input Nodes")
+    parser.add_argument(
+        "--from",
+        action="append",
+        required=True,
+        dest="input_nodes",
+        metavar="NODE_ID",
+        help="Input node (repeatable for multi-input steps)",
+    )
+    parser.add_argument("--title", default=None)
+    parser.add_argument("--type", dest="payload_kind", default=None)
+    parser.add_argument("--payload-type", default="step_payload")
+    parser.add_argument("--field", action="append", default=None, help="Payload field as key=value")
+    parser.add_argument("--json", default=None, help="Payload fields as a JSON object")
+    parser.add_argument("--run", default=None)
+    parser.add_argument("--store-dir", default=None)
+    parser.add_argument("--user", default=None)
+    parser.add_argument("--lane", default=None)
+
+    return parser
+
+
+def run_add_step_command(
+    *,
+    run_id: str,
+    input_node_ids: list[str],
+    title: str | None,
+    payload_kind: str | None,
+    payload_type: str,
+    field_data: dict,
+    json_data: dict,
+    store_dir: str,
+    user_id: str | None = None,
+    lane_id: str | None = None,
+) -> dict:
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    data = dict(json_data or {})
+    data.update(field_data or {})
+    if title is not None:
+        data.setdefault("title", title)
+        data.setdefault("text", title)
+    if payload_kind is not None:
+        data.setdefault("type", payload_kind)
+    else:
+        data.setdefault("type", "step")
+
+    payload = build_payload(
+        payload_type=payload_type,
+        target_kind="step",
+        target_id="pending",
+        payload_id="pending",
+        json_data={},
+        field_data=data,
+    )
+    before = graph_counts(handle)
+    step = handle.add_step(
+        input_node_ids,
+        payload,
+        user_id=user_id,
+        lane_id=lane_id,
+    )
+    maybe_append_or_save(
+        store=store,
+        handle=handle,
+        user_id=user_id,
+        lane_id=lane_id,
+        before=before,
+    )
+    return {"step": step_view(step)}
+
+
+def cli_add(args) -> int:
+    try:
+        result = run_add_step_command(
+            run_id=resolve_run_id_from_args(args),
+            input_node_ids=args.input_nodes,
+            title=args.title,
+            payload_kind=args.payload_kind,
+            payload_type=args.payload_type,
+            field_data=parse_field_args(args.field),
+            json_data=parse_json_object(args.json),
+            store_dir=args.store_dir,
+            user_id=resolve_user_id_from_args(args),
+            lane_id=resolve_lane_id_from_args(args),
+        )
+        print(json.dumps(result["step"], ensure_ascii=False, indent=2))
+        return 0
+    except (KeyError, ValueError, json.JSONDecodeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1

arctx_cli-0.3.1b1/src/arctx_cli/commands/asset.py

@@ -0,0 +1,138 @@
+"""arctx asset command — attach and manage file assets (core payload)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from arctx_cli.append_batch import graph_counts, maybe_append_or_save
+from arctx_cli.context import (
+    resolve_run_id_from_args,
+    resolve_store,
+    resolve_user_id_from_args,
+    resolve_lane_id_from_args,
+)
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    """Register the ``asset`` command namespace."""
+    asset_parser = subparsers.add_parser("asset", help="Asset management commands")
+    asset_sub = asset_parser.add_subparsers(dest="asset_command", required=True)
+
+    sp_attach = asset_sub.add_parser("attach", help="Attach a file to a Node or Step")
+    sp_attach.add_argument("file_path", help="Path to the file to attach")
+    sp_attach.add_argument("--target", required=True, dest="target_id", help="Node or Step ID")
+    sp_attach.add_argument("--run", default=None)
+    sp_attach.add_argument("--store-dir", default=None)
+    sp_attach.add_argument("--user", default=None)
+    sp_attach.add_argument("--lane", default=None)
+
+    sp_list = asset_sub.add_parser("list", help="List assets for a Node or Step")
+    sp_list.add_argument("--target", required=True, dest="target_id", help="Node or Step ID")
+    sp_list.add_argument("--run", default=None)
+    sp_list.add_argument("--store-dir", default=None)
+
+    sp_show = asset_sub.add_parser("show", help="Show details of a specific asset payload")
+    sp_show.add_argument("payload_id", help="Payload ID of the asset")
+    sp_show.add_argument("--run", default=None)
+    sp_show.add_argument("--store-dir", default=None)
+
+    return asset_parser
+
+
+def cli_asset(args) -> int:
+    """Dispatch ``arctx asset`` subcommands."""
+    if args.asset_command == "attach":
+        return _cli_asset_attach(args)
+    if args.asset_command == "list":
+        return _cli_asset_list(args)
+    if args.asset_command == "show":
+        return _cli_asset_show(args)
+    print(f"unknown asset subcommand: {args.asset_command}", file=sys.stderr)
+    return 1
+
+
+def _cli_asset_attach(args) -> int:
+    store = resolve_store(args.store_dir)
+    run_id = resolve_run_id_from_args(args)
+    user_id = resolve_user_id_from_args(args)
+    lane_id = resolve_lane_id_from_args(args)
+
+    if not store.run_path(run_id).exists():
+        print(f"error: unknown run_id: {run_id}", file=sys.stderr)
+        return 1
+
+    handle = store.load_run(run_id)
+    if (
+        args.target_id not in handle.run_graph.nodes
+        and args.target_id not in handle.run_graph.steps
+    ):
+        print(f"error: target_id not found: {args.target_id}", file=sys.stderr)
+        return 1
+
+    try:
+        before = graph_counts(handle)
+        payload = handle.attach_asset(
+            args.target_id,
+            args.file_path,
+            user_id=user_id,
+            lane_id=lane_id,
+        )
+    except (KeyError, ValueError, FileNotFoundError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    maybe_append_or_save(
+        store=store,
+        handle=handle,
+        user_id=user_id,
+        lane_id=lane_id,
+        before=before,
+    )
+    print(json.dumps(payload.to_dict(), ensure_ascii=False, indent=2))
+    return 0
+
+
+def _cli_asset_list(args) -> int:
+    store = resolve_store(args.store_dir)
+    run_id = resolve_run_id_from_args(args)
+
+    if not store.run_path(run_id).exists():
+        print(f"error: unknown run_id: {run_id}", file=sys.stderr)
+        return 1
+
+    handle = store.load_run(run_id)
+    if args.target_id in handle.run_graph.nodes:
+        raw_payloads = handle.run_graph.payloads_for_node(args.target_id)
+    elif args.target_id in handle.run_graph.steps:
+        raw_payloads = handle.run_graph.payloads_for_step(args.target_id)
+    else:
+        print(f"error: target_id not found: {args.target_id}", file=sys.stderr)
+        return 1
+
+    payloads = [
+        p.to_dict()
+        for p in raw_payloads
+        if getattr(p, "payload_type", None) == "asset"
+    ]
+    print(json.dumps(payloads, ensure_ascii=False, indent=2))
+    return 0
+
+
+def _cli_asset_show(args) -> int:
+    store = resolve_store(args.store_dir)
+    run_id = resolve_run_id_from_args(args)
+
+    if not store.run_path(run_id).exists():
+        print(f"error: unknown run_id: {run_id}", file=sys.stderr)
+        return 1
+
+    handle = store.load_run(run_id)
+    payload = handle.run_graph.payloads.get(args.payload_id)
+    if payload is None or getattr(payload, "payload_type", None) != "asset":
+        print(f"error: asset payload not found: {args.payload_id}", file=sys.stderr)
+        return 1
+
+    print(json.dumps(payload.to_dict(), ensure_ascii=False, indent=2))
+    return 0

arctx_cli-0.3.1b1/src/arctx_cli/commands/attach.py

@@ -0,0 +1,115 @@
+"""User-facing arctx attach command."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from arctx_cli.commands._targets import resolve_target_kind
+from arctx_cli.append_batch import graph_counts, maybe_append_or_save
+from arctx_cli.context import (
+    resolve_run_id_from_args,
+    resolve_store,
+    resolve_user_id_from_args,
+    resolve_lane_id_from_args,
+)
+from arctx_cli.payload_builder import build_payload, parse_field_args, parse_json_object
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser("attach", help="Attach a Payload to a Node or Step")
+    parser.add_argument("target_id")
+    parser.add_argument("--type", dest="payload_kind", default="payload")
+    parser.add_argument("--payload-type", default=None)
+    parser.add_argument("--field", action="append", default=None, help="Payload field as key=value")
+    parser.add_argument("--json", default=None, help="Payload fields as a JSON object")
+    parser.add_argument("--run", default=None)
+    parser.add_argument("--store-dir", default=None)
+    parser.add_argument("--user", default=None)
+    parser.add_argument("--lane", default=None)
+    return parser
+
+
+def run_attach_command(
+    *,
+    run_id: str,
+    target_id: str,
+    payload_kind: str,
+    payload_type: str | None,
+    field_data: dict,
+    json_data: dict,
+    store_dir: str,
+    user_id: str | None = None,
+    lane_id: str | None = None,
+) -> dict:
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    target_kind = resolve_target_kind(handle, target_id)
+    if target_kind == "payload":
+        raise ValueError("cannot attach a payload to another payload")
+
+    data = dict(json_data or {})
+    data.update(field_data or {})
+    data.setdefault("type", payload_kind)
+    internal_payload_type = payload_type or (
+        "node_payload" if target_kind == "node" else "step_payload"
+    )
+    before = graph_counts(handle)
+    payload = build_payload(
+        payload_type=internal_payload_type,
+        target_kind=target_kind,  # type: ignore[arg-type]
+        target_id=target_id,
+        payload_id=handle._next_id("pl"),
+        json_data={},
+        field_data=data,
+    )
+    if payload.target_kind == "node":
+        attached = handle.attach(
+            payload.target_id,
+            payload,
+            user_id=user_id,
+            lane_id=lane_id,
+        )
+    else:
+        handle.run_graph.attach_payload(payload)
+        handle.record_work_event(
+            user_id=user_id,
+            lane_id=lane_id,
+            event_type="payload_attached",
+            target_kind="step",
+            target_id=payload.target_id,
+            created_records=(payload.payload_id,),
+        )
+        attached = payload
+
+    maybe_append_or_save(
+        store=store,
+        handle=handle,
+        user_id=user_id,
+        lane_id=lane_id,
+        before=before,
+    )
+    return {"payload": attached.to_dict()}
+
+
+def cli_attach(args) -> int:
+    try:
+        result = run_attach_command(
+            run_id=resolve_run_id_from_args(args),
+            target_id=args.target_id,
+            payload_kind=args.payload_kind,
+            payload_type=args.payload_type,
+            field_data=parse_field_args(args.field),
+            json_data=parse_json_object(args.json),
+            store_dir=args.store_dir,
+            user_id=resolve_user_id_from_args(args),
+            lane_id=resolve_lane_id_from_args(args),
+        )
+        print(json.dumps(result["payload"], ensure_ascii=False, indent=2))
+        return 0
+    except (KeyError, ValueError, json.JSONDecodeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1