`create --image` does not accept Docker tags — GETTING_STARTED.md and flag help are misleading

[hidetaka-cci]

GETTING_STARTED.md and the --image flag help text both imply that a locally built Docker image (or any Docker tag) can be passed to chunk sidecar create --image. In practice, the production API only accepts a snapshot ID from chunk sidecar snapshot create. Passing any Docker tag returns a 400 or 404 error with no guidance.

Steps to reproduce

# Step 1: build an image (succeeds)
chunk sidecar env | chunk sidecar build --tag my-project:latest

# Step 2: create a sidecar from that image (fails)
chunk sidecar create --image my-project:latest

Also fails with:

chunk sidecar create --image cimg/node:26.2.0   # 400 Bad Request
chunk sidecar create --image ubuntu:22.04        # 404 Not Found

Expected behavior

One of the following:

• Docker tags passed to --image work as documented, or
• The error message explains that --image requires a snapshot ID, with a pointer to chunk sidecar snapshot create

Actual behavior

✗ Error: Could not create the sidecar.
  Suggestion: Check your network connection and try again.

No indication that the value passed is invalid or that a snapshot ID is required.

Misleading documentation

GETTING_STARTED.md (lines 203–205):

chunk sidecar env                                    # detect stack, save to config
chunk sidecar env | chunk sidecar build --tag myimg  # build Docker image
chunk sidecar create --image myimg                   # name auto-generated

This implies build and create --image form a connected workflow. They do not.

chunk sidecar create --help:

--image   E2B template ID or container image

"container image" suggests Docker tags are accepted. They are not.

What --image actually accepts

Only a snapshot ID produced by:

chunk sidecar snapshot create --name <name>
# → returns a snapshot ID
chunk sidecar create --image <snapshot-id>   # this works

This is correctly described in chunk sidecar snapshot create --help, but is not surfaced in create --help or the getting started guide.

Suggested fix

1. GETTING_STARTED.md: Remove or replace the build → create --image example. Document the correct first-time flow:

   chunk sidecar create              # default sidecar
   # ... install runtime, run setup ...
   chunk sidecar snapshot create --name my-snapshot
   chunk sidecar create --image <snapshot-id>
   

2. --image flag help: Clarify that only snapshot IDs are accepted:

   --image   Snapshot ID (from 'chunk sidecar snapshot create')
   

3. Error message on 400/404: Add a hint:

   Suggestion: --image requires a snapshot ID. Create one with 'chunk sidecar snapshot create'.
   

Workaround

# 1. Create a default sidecar and provision the runtime manually
chunk sidecar create --org-id <orgID>
# install required runtime via chunk sidecar exec

# 2. Run setup
chunk sidecar setup --skip-sync

# 3. Snapshot
chunk sidecar snapshot create --name <project>-snapshot
# → <snapshot-id>

# 4. Future sidecars can use the snapshot
chunk sidecar create --image <snapshot-id>

Environment

• chunk-cli version: 1.2.0 / 1.3.0
• OS: macOS
• Docker Desktop: running