Command Catalog

CodeMesh command docs separate current commands from planned behavior. The current command list below is checked against top-level CLI help and the stable command reference pages by TestCommandCatalogMatchesTopLevelHelp and TestCommandReferencePagesMatchCatalog.

#Current Commands

Each linked reference page documents the current syntax, purpose, safe local examples, and current limitations. If a command does not appear in this list, it is not part of the runnable MVP surface.

codemesh env bind stores provider-specific secret references in local CodeMesh state, outside repo-local Project Policy. The first runnable provider is deterministic fake, for local tests and agent-scoped bundle proof only.

codemesh hydrate, codemesh access, and codemesh agent prepare use the full-clone Clone Strategy by default: full Git history and a complete working tree. --partial-clone opts into Git partial clone with blob:none; repeatable --sparse path opts into Git sparse checkout. These are Git-native lazy clone/checkouts, not mounts, VFS behavior, daemon hydration, or file-level sync.

codemesh agent prepare prints the ready workspace path plus handoff_docs: N, where N is the count of selected handoff docs. The detailed handoff doc metadata is path-only in the versioned codemesh-run.json Agent Run Contract; CodeMesh does not copy docs, embed doc contents, or read doc contents into metadata. With --env-provider fake and matching --allow-env-scope, Agent Prep can materialize an env bundle under the managed run directory, outside the prepared Git checkout. The contract records clone strategy metadata, requirement names, allowed scopes, bundle presence/path, and values: not-recorded.

codemesh doctor runs the same handoff readiness preflight as Agent Prep but does not create an agent workspace, write codemesh-run.json, or record an Agent Run. --strict makes warning-only readiness exit non-zero for automation while preserving normal Agent Prep warning behavior.

Repo-local Project Policy may declare toolchain readiness requirements. doctor reports checked toolchain status in human and JSON output, and agent prepare records status in the Agent Run Contract. Present host detections record command names and versions while project facts keep the declared requirement separate. Toolchain readiness is report/delegate only; CodeMesh does not install tools or build environments.

codemesh agent run is separate from prepare. Prepare creates and records the workspace; run executes one explicitly supplied local command inside that prepared workspace, captures stdout/stderr to managed files, and records command metadata without env values.

#Safe Local Example

This example uses a temp CodeMesh home and local Git remote only. It does not touch the user's normal CodeMesh home, personal workspace, GitHub account, or secrets.

demo="$(mktemp -d)"
export CODEMESH_HOME="$demo/codemesh-home"
workspace="$demo/workspace"
seed="$demo/seed"
remote="$demo/demo.git"

mkdir -p "$workspace" "$seed"
git -C "$seed" init -b main
printf '# demo\n' > "$seed/README.md"
git -C "$seed" add README.md
git -C "$seed" -c user.name='CodeMesh Demo' -c user.email='demo@example.invalid' commit -m 'Initial demo'
git clone --bare "$seed" "$remote"
git clone "$remote" "$workspace/demo-project"

codemesh init "$workspace"
codemesh machine register "$workspace" --name "Demo Machine"
codemesh add "$workspace/demo-project" --alias demo-project
codemesh tree
codemesh tree --json
codemesh status demo-project --base main
codemesh status demo-project --base main --json
codemesh doctor demo-project --base main
codemesh doctor demo-project --base main --strict --json
codemesh env bind demo-project CODEMESH_DEMO_KEY --provider fake --ref fake://demo-key --scope codex
codemesh agent prepare demo-project --base main --profile codex
codemesh agent prepare demo-project --base main --profile codex --env-provider fake --allow-env-scope codex
codemesh agent prepare demo-project --base main --profile codex --json
run_id="$(codemesh runs | awk '/^- / {print $2; exit}')"
codemesh agent run "$run_id" --label workspace-root -- git rev-parse --show-toplevel
codemesh runs
codemesh clean --older-than 0d

Use codemesh scan "$workspace" instead of codemesh add ... when discovering all Git checkouts under a workspace root.

Use codemesh hydrate <project> after a project is already registered and its desired local path is missing. Hydration uses the shared Hydration Planner to classify present, missing, path-conflict, unsafe-path, and unknown-project states before cloning the registered remote into the planned path.

Use codemesh access <project> when a user or agent explicitly touches a known Project by command and wants CodeMesh to hydrate missing or Placeholder content first. Access-triggered lazy Hydration reports trigger: command-access plus a missing/placeholder/hydrated transition in JSON output, then tree and status show the derived final workspace state.

Use codemesh bootstrap --all or codemesh bootstrap <project>... after Projects are registered to preview planned clone/refusal actions on the current machine. Add --dry-run to make preview mode explicit. Add --placeholders to refuse blockers and write metadata-only sentinel directories for missing planned Projects. Add --apply to refuse blockers before Git and clone missing planned Projects into their desired paths. codemesh bootstrap <manifest-path> --apply and --placeholders still import manifest topology first, then consume the same Hydration Planner actions for clone or placeholder execution.

Use codemesh manifest export --output <path> on a registered machine to write the canonical Workspace Manifest as a deterministic portable JSON file. Use codemesh manifest import <path> on another registered machine to validate that manifest and persist matching Project Registry rows under that machine's workspace root.

Use codemesh target export <target-name> --scope scope --json after codemesh machine register to package the current manifest topology, local machine facts, target facts, and scoped Env Binding references into a target-ready JSON contract. The export is local-only and does not contact Coder, DevPod, Daytona, or any live provider.

#Planned Or Unimplemented

These directions remain product direction, not runnable commands today:

multi-machine sync
synced manifests or remote project indexes
live secret providers or env file writing
daemon, mount, UI, automatic placeholders, path-triggered lazy hydration, or file-level lazy hydration
generic cloud drive behavior

Research docs may sketch future commands for those areas. Treat them as planned until they appear in current CLI help and this catalog.

The current Workspace Manifest command surface writes and imports one deterministic JSON file with schema version and sorted project topology: project identity, alias, relative desired path, clone hints, and grouping. Legacy bootstrap input remains one JSON entry file or a directory of small per-project desired-topology entries. Manifest files must not export observed readiness, dirty/stale status, Agent Runs, machine facts, env values, or secret values. target export wraps that desired topology with target/machine facts and scoped Env Binding references for future adapters. Coder, DevPod, and Daytona are future adapters over this target shape, not integrations in this command.