@code3d/cli

Command-line access to the project open in Code3D. The App owns files, versions, saving, model execution, and receipts. Node.js 24+ is required.

npx --yes @code3d/cli@latest /absolute/path/to/project.c3d.json serve

Run serve through the current agent session's managed process tool, keeping stdin or a PTY open. It emits a JSON listening event and stays in the foreground. EOF, closed stdin, SIGINT, SIGTERM, or SIGHUP closes the listener and releases its port. The host must close the managed pipe/PTY or terminate the process when the session ends; do not detach it, use nohup, or restart the agent conversation.

While it runs, send one complete JSON document through stdin for each invocation:

echo '{"operation":"context"}' | npx --yes @code3d/cli@latest project.c3d.json
echo '{"operation":"fs.read","path":"/model.ts"}' | npx --yes @code3d/cli@latest project.c3d.json
npx --yes @code3d/cli@latest project.c3d.json --request-id edit-001 < change.json
echo '{"operation":"result","requestId":"edit-001"}' | npx --yes @code3d/cli@latest project.c3d.json

For example, change.json contains the entire request:

{
  "operation": "apply",
  "input": {
    "files": [
      {
        "path": "/model.ts",
        "version": "<read version>",
        "content": "<full source>"
      }
    ],
    "cursor": {"file": "/model.ts", "regex": "(box\\(10, 6, 8\\))"},
    "render": {"view": "front"},
    "topology": true,
    "type": true
  }
}

Multi-line JSON is supported; stdin EOF ends the request. The CLI and local bridge pass the payload to the App without interpreting or normalizing operation fields. The App owns schema validation. New App operations and parameters do not require a CLI update while the connection and response envelope stay unchanged. The current App accepts one operation, not a batch or JSON Lines stream.

Only execution options remain on the command line: --request-id, --timeout and --output-dir. serve starts the session-managed connection service. Operation subcommands and observation flags are not part of the CLI interface.

The App supplies a private config with port, origin, sessionId, agentId, name, and key. Keep the page open and permit local-network access. One process binds each grant's port on 127.0.0.1; multiple agents use separate ports. Port conflicts are explicit. Revoke/Revoke all stops App retries and removes authorizations; the local process remains owned by its agent host.

Operations emit JSON; artifacts are local files with paths in the result. Artifacts are saved for successful and failed responses alike. A model_failed response can include an inspect image and topology under error.details.observation; the CLI still exits with code 1. An artifact write failure reports the remote result without inline binary data, so its original status remains available. Transport errors distinguish a missing service from a disconnected App and an unknown execution outcome, and include executable recovery instructions. Retain a mutation ID before sending; query it after uncertain outcomes. A not_sent delivery state concerns only the current attempt, not that ID's earlier history. To execute a recovery lookup without a shell, use recovery.queryArgv together with recovery.queryStdin, closing stdin after writing it; queryCommand includes the equivalent POSIX-shell JSON pipe.

See the agent Markdown entry for the required workflow and complete topic directory. Detailed pages cover connection, files and npm dependencies, cursor and arguments, rendering and topology, and recovery. The website introduction explains collaboration features for App users.

Development

From the repository root:

npm run build:packages
npm test --workspace @code3d/cli

To test this checkout after building, run node packages/cli/bld/main.js --help from the repository root. Public workflow commands use @code3d/cli@latest; do not rely on them to select an unpublished checkout or a global link.

• CLI entry: stdin JSON, execution options, artifacts and recovery output.
• Service lifecycle: session-managed stdin/PTY and shutdown.
• Local bridge: authenticated loopback HTTP/WebSocket exchanges.
• Shared transport SDK and CLI process tests.