img2-environment

img2-environment CLI

Installer and management CLI for the private img2threejs/plugin-environment plugin. This public npm package contains only the installer. It does not contain private plugin tools, reference material, pipeline implementation, or provider assets.

Quick start

Prerequisites: Node.js >=18, Git, Python >=3.10, an installed Claude Code/Codex/OpenCode host, and GitHub access to the private plugin repository. Authenticate Git before installing; gh auth login followed by gh auth setup-git is one supported setup. Hermes is not supported by the img2 plugin harness at this time.

# Preview only: no downloads or filesystem changes.
npx img2-environment install --dry-run

# Install the img2 harness if missing, then the private environment plugin.
# --yes explicitly approves the harness setup prompt; it does not bypass GitHub access controls.
npx img2-environment install --yes
npx img2-environment doctor

Or install the CLI globally:

npm install -g img2-environment
img2-environment install --yes
img2-environment doctor

For a project-local CLI:

npm install img2-environment
npx img2-environment install --yes

Installing an npm CLI alone does not install an agent skill or start a reconstruction. The install command initializes the canonical img2 harness and registers the plugin; agent skills link to the installed plugin under $IMG2_HOME (default ~/.img2). The shared runtime comes from @img2threejs/img2; its executable remains img2. This CLI's default installation pins plugin commit c19f5f2bd8ed1b544a026adfc69c46f1b6a237a6 (plugin version 0.1.0). CLI versions are independent of plugin versions. Newer local plugin development is not included in this installer or published to npm.

Install output shows real phases, ref/pin details, host links and the next command. Dry-run and already-registered installs use the same layout without claiming a health check. Color is terminal-only; NO_COLOR=1 or TERM=dumb disables it. Piped output stays plain, narrow terminals wrap without truncating values, and doctor --json stays machine-readable.

Run the plugin, not the installer

After installation, invoke /img2-environment in your supported agent host with your reference image and target workspace. The installed SKILL.md defines the pipeline and required evidence. Installation is not a claim that an environment reconstruction has passed its acceptance gate. Provider dependencies and rendering/review remain explicit prerequisites.

Manage the installation

npx img2-environment --version
npx img2-environment update --check
npx img2-environment update --yes
npx img2-environment remove --yes

update follows the registered source's release policy through the harness. Git plugin updates need a semantic vX.Y.Z tag; an untagged source has no newer release to compare. An existing local --link registration or another source is not silently replaced. Use --home /absolute/path to select a separate harness home, or a pinned --ref on install when you intentionally select another release. The shared CLI's --help lists supported flags. doctor audits the installed harness and plugins; it does not run a model or renderer.

Release this CLI

The package root is cli/, separate from private plugin content. Tags cli-vX.Y.Z must match cli/package.json; plugin tags vX.Y.Z are independent. The root workflow .github/workflows/cli-publish.yml publishes the installer through npm trusted publishing. Configure the npm package's GitHub trusted publisher for organization img2threejs, repository plugin-environment, workflow filename cli-publish.yml, and allow direct npm publish. The private repository publishes without provenance; no npm write token is stored in Actions.

With npm >=11.15 and account-level 2FA, the equivalent command is:

npm exec --yes --package=npm@11 -- npm trust github img2-environment \
  --repo img2threejs/plugin-environment --file cli-publish.yml --allow-publish --yes

The package must already exist on npm. Initial publication is manual; subsequent CLI tags use OIDC.

npm --prefix cli test
npm --prefix cli run package:check
# Bump cli/package.json and update CLI release notes first, then commit reviewed CLI files.
git tag -a cli-v0.1.2 -m 'img2-environment CLI 0.1.2'
git push origin cli-v0.1.2

Never publish from the plugin repository root: npm would automatically include its README. For first publication, use the authorized npm account from cli/; configure trusted publishing before releasing the next CLI tag. Keep plugin content private until a separate explicit release.

CLI release notes

• 0.1.2: polished install/preview/status output through @img2threejs/img2@0.2.5. Plugin content and the immutable c19f5f2 source pin are unchanged.
• 0.1.1: release through the SHA-pinned, tested-artifact GitHub OIDC workflow. Runtime remains exactly @img2threejs/img2@0.2.4, with immutable plugin commit c19f5f2.
• 0.1.0: initial public installer-only npm package for the private environment plugin.