Igny CLI — Beta User Guide

CLI: igny Audience: Igny CLI users Version: populated from the package release version during docs publishing Status: Beta documentation

Igny is the command-line interface to the Crucible workbench — a reproducible tooling layer for hardware and silicon design. It installs the EDA tools you need (simulators, synthesis tools, cross-compilers, Python libraries), keeps each project's tools isolated in a named environment, and lets you run them without polluting your system or fighting PATH.

This guide covers the stable, supported path: create an environment, create a workspace, install tools, run them, and lock the result so a teammate can reproduce it exactly. Every command below includes a real example and the output you should expect.

For product information, visit www.ignytion.io. For support or questions, contact info@ignytion.io.

---

Table of Contents

1. Core Concepts
2. Check Your Installation
3. Quick Start
4. Where Crucible Keeps Things
5. Environments
6. Workspaces
7. Workspace Status
8. Installing and Inspecting Tools
9. Installing a Compiler by Target
10. Running Tools
11. Running Scripts
12. Lock and Reproduce a Workspace
13. Discovering Tools
14. Diagnostics
15. Registry Cache
16. Environment Variables Reference
17. Troubleshooting
18. End-to-End Recipes
19. Inspecting Your Installed CLI

---

1. Core Concepts

Igny has four concepts. Once these click, every command makes sense.

Concept	What it is	You see it with
Catalog tool	A tool Crucible knows how to get (it may not be installed yet)	igny catalog
Installed tool	A tool actually present on this machine	igny tool list
Environment	A named, isolated set of tool bindings (think: a project's toolbox)	igny env ...
Workspace	A project directory bound to one environment	igny workspace ...

The normal lifecycle is:

create / pick an environment   →   create a workspace bound to it
        →   install or sync tools into it
        →   lock the tool state
        →   run tools, scripts, or flows

Two ideas that trip people up

A tool is installed on the machine, then bound to an environment. The heavy payload (the simulator binary, the toolchain) is downloaded once into a shared machine inventory. Each environment then holds a lightweight binding to that payload. Installing the same tool into a second environment does not download it again — it just adds another binding. This is why igny tool uninstall is careful: it removes the machine payload only when no environment still references it.

"Selected" environment vs. "active" environment.

• The selected environment is the one recorded in your workspace's crucible.toml. It's a per-project preference. Set it with igny workspace bind (pointer only) or igny env use --workspace.
• The active environment is a machine-global runtime state (what's "turned on" right now). Set it with igny env activate / igny env use.

Most of the time they line up. When igny run needs to pick an environment, it resolves in this order:

1. CRUCIBLE_ENV environment variable
2. the workspace-selected environment (crucible.toml)
3. the last activated environment
4. the managed default workspace's environment

---

2. Check Your Installation

Print the CLI version:

igny --version

0.0.7

(igny -V is a short alias for the same thing.)

Show the top-level help and command groups:

igny --help

The main command groups you'll use:

igny env ...         manage environments (toolboxes)
igny workspace ...   manage project directories
igny tool ...        install / inspect tools
igny compiler ...    install compilers by target triplet
igny run ...         run a bound binary or a script
igny catalog         browse the supported tool catalog
igny status          show where you are
igny doctor          run diagnostics
igny cache ...        manage the registry cache

---

3. Quick Start

The fastest path from nothing to a running tool.

3.1 One-line sequence

igny env create mysim
igny workspace create --path ./chip_design --env mysim
cd ./chip_design
igny tool install gtkwave
igny run gtkwave

3.2 Step by step (with expected output)

Create an environment — your project's toolbox. Note that creating it does not activate it:

igny env create mysim

Environment 'mysim' created (stack=default)

Create a workspace and bind it to that environment:

igny workspace create --path ./chip_design --env mysim

Workspace 'chip_design' created (env=mysim)

Move into the workspace (tool commands run inside it bind to its environment):

cd ./chip_design

Install a tool into the workspace environment:

igny tool install gtkwave

Installed gtkwave@3.3.116
  Source: artifact
  Path: /home/you/Crucible/tools/gtkwave/3.3.116
  Bound to env: mysim

Run it:

igny run gtkwave

3.3 If you created the workspace before the environment

If a workspace already exists but points at the wrong (or a missing) environment, create the environment and re-point the workspace:

cd ./chip_design
igny env create mysim
igny workspace bind mysim
igny tool install gtkwave
igny run gtkwave

---

4. Where Crucible Keeps Things

Tool payloads live under a single visible location, overridable with an environment variable.

Platform root — where tool payloads live. Default ~/Crucible/:

~/Crucible/
  tools/
    <tool-name>/<version>/

Override with CRUCIBLE_ROOT:

export CRUCIBLE_ROOT=/opt/crucible

Note: Your project directory stays yours. Crucible keeps its own configuration and run logs outside your project tree. The one file Crucible adds to your project is crucible.toml (and crucible.lock once you explicitly lock).

---

5. Environments

An environment is a named, isolated toolbox. Tools you install while a workspace is selected to an environment get bound to that environment.

Create

igny env create sim
igny env create sim --stack default     # optional stack label

Environment 'sim' created (stack=default)

Creating an environment does not activate it — do that explicitly with igny env activate or igny env use.

Naming rules (shared by environments and workspaces): start with a lowercase letter; use only lowercase letters, digits, -, and _; no trailing hyphen; no consecutive hyphens (--); max 63 characters. Underscores are unrestricted (my_env, tmp_act_1 are fine). A bad name fails before anything is written to disk.

List

igny env list

* default (stack=default) [0 tools]
  sim (stack=default) [4 tools]
~ fw-build (stack=default) [2 tools]

Markers: * = the last activated (current) environment, ~ = another active environment, no marker = inactive. [N tools] is how many tools are bound.

Inspect one environment

igny env show sim

Environment: sim
  Stack:    default
  Status:   current (active)
  Flags:    deletable
  Tools:    2
    - verilator  5.020  [artifact]
    - cocotb     1.9.2  [pip]
  Workspaces: 1
    - /home/you/projects/uart-soc

Status is one of current (active) (the cursor points here), active (on but not the cursor), or inactive. The reserved default environment shows reserved (not deletable).

Activate / deactivate

igny env activate sim

Activated environment 'sim'

igny env deactivate sim

Deactivated environment 'sim'

Deactivating is idempotent (deactivating something already inactive still exits 0) and never deletes the environment or its bindings.

Tier limits: on the community tier only one environment can be active at a time. If you activate a second one, Igny asks whether to deactivate the current one first. In a script or CI (no terminal), pass --yes to confirm automatically, or run igny env deactivate <other> first.

Activate and point the workspace at it

igny env use activates an environment for the current context:

igny env use sim                # activate only
igny env use sim --workspace    # activate AND set it as the workspace's selected env
igny env use sim --no-activate --workspace   # only update the workspace pointer

Activated environment 'sim'
Workspace 'uart-soc' now uses environment 'sim'

If you only want to change which environment a workspace points at without activating it, use igny workspace bind (below).

Open a shell with the environment's tools active

igny env shell drops you into an interactive subshell where every bound tool is on your PATH and every bound Python library is importable — like activating a virtualenv, but for your whole toolbox:

igny env shell sim      # a named environment
igny env shell          # the resolved environment for the current context

$ igny env shell sim
Entering Crucible env shell — bound tools active. Type 'exit' to leave.
$ verilator --version
Verilator 5.020 2024-01-01
$ python -c "import cocotb; print(cocotb.__version__)"
1.9.2
$ exit
Left Crucible env shell.

The subshell sets $IGNY_ENV to the environment name. Leaving it restores your original shell exactly — nothing global is changed — and the subshell's exit code becomes the command's exit code.

Rename

igny env rename sim sky130-sim

Environment 'sim' renamed to 'sky130-sim'.
Warning: workspace 'uart-soc' is still bound to 'sim'.
  Run: igny workspace bind sky130-sim --path /home/you/projects/uart-soc

The directory, metadata, and active state are updated atomically. Workspaces bound to the old name are not auto-updated — the warning gives you the exact repair command for each one. The warning block is omitted when nothing references the old name.

Export / import

Move an environment between machines as a zip archive:

igny env export sim ./sim-env

Exported environment 'sim' to ./sim-env.zip

igny env import ./sim-env.zip

Imported environment 'sim'

The archive's filename stem becomes the imported environment name. Importing over an existing name fails; neither command restores active runtime state.

Delete

igny env delete sim

Deleted environment 'sim'

Deletion is refused (non-zero exit) for: a missing environment, the currently active environment, the reserved default environment, or an environment still referenced by a workspace. Deactivate or re-bind first, then delete.

---

6. Workspaces

A workspace is any project directory that contains a crucible.toml. It records the project's identity and its selected environment.

Create

igny workspace create my-chip --path ./my-chip --env sim   # named, in a new dir
igny workspace create --env sim                            # in the current dir
cd my-chip

Workspace 'my-chip' created (env=sim)

Workspace creation is marker-based: the important artifact is crucible.toml. If --env is omitted, the active environment is used; if <name> is omitted, the directory name becomes the workspace name.

igny workspace create refuses to overwrite an existing workspace and exits non-zero if --env names an environment that doesn't exist.

Inspect

igny workspace show

Name        : my-chip
Type        : Custom
Path        : /home/you/projects/my-chip
ID          : 7f3a9c21
Environment : sim
Known Envs  : sim, fw-build
Default Flow: -
Lock File   : Missing

Type is Custom for your projects and Managed for the system default workspace. Lock File is Present once you run igny workspace lock.

List

igny workspace list

  guardian-asic   /home/you/projects/guardian-asic
  my-chip         /home/you/projects/my-chip

The list is global to your install. On a fresh machine it prints No workspaces registered. and still exits 0.

Bind to a different environment

A pure pointer update — changes the workspace's selected environment without activating it:

igny workspace bind sim

Workspace 'my-chip' bound to environment 'sim'

Use igny env use sim --workspace if you want to activate and bind in one step.

Rename

Run from inside the workspace:

igny workspace rename my-chip-v2

Workspace 'my-chip' renamed to 'my-chip-v2'

The workspace ID stays stable across a rename; only the display name changes (in both crucible.toml and the registry).

Delete (unregister)

igny workspace delete --yes
igny workspace delete --path ./my-chip --yes

Workspace 'my-chip' unregistered from Crucible tracking.
Project files preserved: /home/you/projects/my-chip

This only removes the workspace from Crucible's registry — your project files and crucible.toml stay on disk. Omit --yes to be prompted. The managed default workspace cannot be deleted.

---

7. Workspace Status

igny status is a read-only, top-level command that tells you where you are. It never creates or modifies anything, so it's safe to run anytime — even on a machine where Crucible has never been configured.

igny status
igny status --path ./my-chip    # inspect a directory without cd-ing into it

Inside a workspace:

Workspace : uart-soc
Path      : /home/you/projects/uart-soc
Env       : sim  [active]
Tools     : 3
Lock file : present

Outside any workspace:

Workspace : none

The [active] / [inactive] tag shows whether the workspace's bound environment is currently in the active set.

---

8. Installing and Inspecting Tools

How installs are bound

Where you run it	What happens
Inside a workspace	Installed into the machine inventory and bound to the workspace's selected environment
Outside a workspace	Installed into the machine inventory and bound to the managed default environment

Tools come from three acquisition families, chosen automatically per tool:

Source	Meaning
pip	A Python package installed into Crucible's isolated tool directory
artifact	A prebuilt archive downloaded and extracted
docker	A Docker image pulled or referenced

Artifact installs verify size/checksum metadata when available and repair a stale cached archive by downloading it once more before failing the install.

For pip-backed tools that expose a command, Crucible writes a self-contained launcher next to the install so the tool runs correctly through igny run, inside igny env shell, or directly — and the package stays importable.

Install

igny tool install verilator
igny tool install fusesoc --version 2.4.5    # a specific version

Inside a workspace:

Installed verilator@5.020
  Source: artifact
  Path: /home/you/Crucible/tools/verilator/5.020
  Bound to env: sim

If it's already present:

verilator@5.020 is already installed

List installed tools

igny tool list

Installed tools:
  verilator@5.020 (artifact)
  fusesoc@2.4.5 (pip)

On an empty machine: No tools installed.

Check whether a tool is installed

igny tool check verilator
igny tool check fusesoc --version 2.4.5

verilator is installed
fusesoc@2.4.5 is installed

Exits non-zero (with a ... is not installed message) when the tool or the requested version is missing — handy in scripts.

Inspect a tool in depth

igny tool show gives a four-part view of everything Crucible knows about a tool or about a single binary a tool provides:

igny tool show verilator
igny tool show vvp            # vvp is provided by iverilog
igny tool show verilator --env fw-build   # resolve against a specific env
igny tool show verilator --json           # machine-readable

The four blocks are:

1. Resolved for current context — exactly what igny run <name> would execute right now, and whether it's runnable.
2. Catalog — whether it's a known catalog tool, its domains and sources, and the binaries it provides. If you ask about a companion binary (like vvp), this names its provider and the install hint (igny tool install iverilog).
3. Installed on this machine — which versions are installed.
4. Environment bindings — which environments bind a package providing this name.

This is the command to reach for when igny run says a binary isn't bound — it tells you which package provides it and how to install it.

Unbind (keep the payload, drop the binding)

igny tool unbind fusesoc
igny tool unbind fusesoc --all-envs

Removes the tool's binding from the current environment but leaves the machine-installed payload (and any other environments' bindings) intact. Use --all-envs when you want to remove the binding from every environment without deleting the shared payload. That is often the clean first step before a complete uninstall:

igny tool unbind fusesoc --all-envs
igny tool uninstall fusesoc

--all-envs does not override any safety guard and does not touch the payload. It only removes environment bindings, so you can bind the tool again later from the machine inventory without downloading it again.

Repair a corrupt payload

igny tool install fusesoc --repair

Normal igny tool install <tool> already heals missing files when a binding points at a payload that is no longer runnable. Use --repair for the harder case: files are present but the payload is corrupt, truncated, half-extracted, or otherwise wrong. Repair re-acquires and re-extracts the same machine payload and reports Repaired ....

--repair is not a guard override. It replaces the old no-op tool install --force flag, which is now removed. In Igny, --force means "override a guard" and appears only on commands where there is a guard to override.

Uninstall

igny tool uninstall fusesoc 2.4.5
igny tool uninstall fusesoc          # version derived when only one is bound
igny tool uninstall fusesoc --force  # override non-active env references

Uninstalled fusesoc@2.4.5

Uninstall is forgiving. It first unbinds the tool from your current environment, then removes the machine payload only if no other environment still references it. If another environment still uses it, that's not an error — the payload is kept and you get a notice:

Unbound fusesoc from 'sim'. Payload retained — still referenced by env(s): fw-build

It exits non-zero only for genuine problems: the version isn't installed, the version is ambiguous and you didn't specify one, or files can't be removed.

Use --force only when you deliberately want to remove the machine payload even though another environment still binds it. --force can override the "referenced by another environment" guard, but it cannot override a live environment: if any environment binding that tool is active, the command refuses and changes nothing. When a forced uninstall succeeds, the other environments' bindings are left dangling and will self-heal on the next igny tool install or igny workspace sync.

---

9. Installing a Compiler by Target

The igny compiler group is a convenience lens over the tool catalog: you speak in target triplets (riscv32, riscv-none-elf) and Igny resolves them to the right catalog tool (e.g. riscv32-gcc). Anything installed this way is an ordinary tool — it shows up in igny tool list, binds to environments, and runs via igny run with no special handling.

List available compilers

igny compiler list

One row per compiler/toolchain, with its target name, whether it's installed, and the binaries it provides.

Show a target

igny compiler show riscv32

If the target you typed resolves to a differently-named tool, Igny prints a note first:

Resolved target 'riscv32' → riscv32-gcc

…followed by the same four-block view as igny tool show.

Resolution order (within Compiler-domain tools only):

1. Exact catalog tool name — riscv32-gcc
2. Exact provided-binary name — riscv32-buildroot-linux-musl-gcc
3. Prefix match — riscv32 → riscv32-gcc

Install

igny compiler install riscv32
igny compiler install riscv-none-elf --env fw-build   # into a specific env
igny compiler install riscv32 --version 14.2.0

After install, every binary the toolchain ships is runnable directly:

igny run riscv32-buildroot-linux-musl-gcc --version

Uninstall

igny compiler uninstall riscv32
igny compiler uninstall riscv-none-elf --env fw-build

This unbinds the toolchain from the resolved environment and removes it from the machine once nothing else references it — exactly like igny tool uninstall.

Ambiguous targets

If a bare target matches more than one toolchain (for example riscv matches riscv32-gcc, riscv64-gcc, and riscv-none-elf-gcc), Igny refuses to guess: it lists the candidates and asks you to be more specific.

Target 'riscv' is ambiguous. Matching compilers:
  - riscv32-gcc
  - riscv64-gcc
  - riscv-none-elf-gcc
Specify a more precise target.

---

10. Running Tools

Run any binary provided by the current workspace's environment, by name:

igny run verilator --version

Everything after the binary name is passed verbatim to the tool — no -- separator is needed, and igny run exits with the tool's own exit code. If the tool fails, Igny leaves the tool output visible, adds a Run failed: summary, and prints a Full output: pointer to the captured run log when one is available. On POSIX systems, signal-killed tools use the normal shell 128+N exit status convention.

Override the environment for one run with --env, placed before the binary name:

igny run --env sim verilator --version

Because --env is only recognized before the binary name, a tool that has its own --env flag still receives it untouched (igny run mytool --env prod passes --env prod to mytool).

Multi-binary packages resolve transparently. If iverilog declares provides = ["iverilog", "vvp"], both work without a separate vvp binding:

igny run iverilog -o sim.vvp tb.v
igny run vvp sim.vvp
igny run yosys -p "synth -top top; write_json out.json" rtl.v

Interactive tools attach to your current terminal: terminal tools like yosys and renode show their normal prompt/banner; GUI tools like gtkwave launch normally.

Where you run it

You can run igny run from anywhere inside your workspace — including a subdirectory. Crucible finds the workspace by walking up from your current directory. The tool launches in the folder you're standing in, so relative paths (input files, output files) resolve against your current directory.

Choosing the environment

The direct igny run <binary> form has no --env flag (so it can forward everything to the tool). To override the environment, set CRUCIBLE_ENV:

CRUCIBLE_ENV=fw-build igny run riscv-none-elf-gcc --version

When a binary isn't bound

If igny run <binary> reports the binary isn't bound, find its provider and install it:

igny tool show vvp          # → provided by iverilog; hint: igny tool install iverilog
igny tool install iverilog

Reserved-name escape hatch

If a binary's name collides with a reserved igny run sub-command (such as script or tool), disambiguate with --binary:

igny run --binary script my_arg

More examples

igny run gtkwave
igny run fusesoc --version
igny run verilator --version
igny run yosys
igny run renode

---

11. Running Scripts

Run a script with your workspace environment's context applied (its tools on PATH, its libraries importable). You can run it from anywhere inside your workspace — including a subdirectory — and the script launches in the folder you're standing in, so relative paths resolve against your current directory. The script's output streams straight to your terminal:

igny run script ./scripts/build.py

R=8.20 kOhm
PASS opamp_square_wave_generator
Script completed successfully

Pass arguments to the script after --:

igny run script ./scripts/build.py -- --target sim --jobs 4

A failing script reports its exit code and exits non-zero:

Script failed (exit code 2)

Every run's output is captured to a log automatically. Add --log to print the path to that log on success (it is always shown when a script fails). Use --quiet to keep the terminal clean (pair it with --log to capture to the log only):

igny run script ./scripts/build.py --log

---

12. Lock and Reproduce a Workspace

This is how you make a project reproducible for teammates and CI.

After installing and binding the tools your project needs, write a lock file from inside the workspace:

igny workspace lock

Locked workspace 'my-chip' (env='sim') — 3 tool(s) -> crucible.lock

This writes crucible.lock, capturing each bound tool's name, version, source, paths, and checksum/URL where available. Commit both files together:

crucible.toml
crucible.lock

On another machine, after cloning the project:

git clone <project-repo>
cd <project>
igny workspace sync

Synced 3 tool(s) to environment 'sim': verilator, cocotb, fusesoc

sync reads the lock, installs any missing tools into the machine inventory, and binds them to the environment named in crucible.lock. If that environment does not exist on this machine, sync creates it. If crucible.toml points at a different environment, sync repoints the workspace to the lock's environment. Re-running it is idempotent:

Already bound: verilator, cocotb, fusesoc

Notes: sync treats crucible.lock as the reproduction source of truth and has no separate environment override flag. The managed default workspace cannot be synced. Regenerate crucible.lock after a CLI upgrade rather than assuming forward compatibility.

---

13. Discovering Tools

Browse the catalog of tools Crucible knows how to acquire (not just installed ones):

igny catalog                 # compact view, grouped by domain
igny catalog --view full     # names, install state, domains, descriptions
igny catalog --tag simulation
igny catalog --tag vp        # 'vp' and 'simulation' expand to the same cluster

--tag is repeatable to combine filters.

Design suites

A design suite is a named, versioned bundle of tools for a task — for example, a minimal RTL simulation setup — so you can pull a whole capability instead of remembering each tool by hand.

Shipped suites include sim-basic (a minimal Icarus Verilog / Verilator simulation setup) and riscv-suite (a RISC-V + Chisel/Scala bundle: a JVM build stack with temurin-jdk and mill, bare-metal riscv-none-elf-gcc, and RTL simulation with Verilator and GTKWave, plus optional Linux toolchains, renode emulation, and synthesis/FPGA tools).

Browse the available suites:

igny suite list

Look inside one to see the tools it bundles, which are required, which are optional, and any pinned versions:

igny suite show sim-basic

A suite has two verbs, matching the two things you might want. acquire downloads the tools onto your machine; install also makes them usable in your current environment.

Download a suite's tools onto your machine:

igny suite acquire sim-basic                       # required tools
igny suite acquire sim-basic --with verilator      # add an optional tool
igny suite acquire sim-basic --all-optional        # add every optional tool

Install a suite — download its tools and make them usable with igny run in your current environment:

igny suite install sim-basic                       # required tools
igny suite install sim-basic --with verilator      # add an optional tool
igny suite install sim-basic --all-optional        # add every optional tool
igny suite install sim-basic --env lab             # into a named environment

For both verbs, required tools are always included; optional tools are opted in with --with (repeatable) or --all-optional. Every tool is attempted and you get a per-tool result plus a summary — a tool already in the environment at the same version is left in place, and if any tool fails the command reports it and exits non-zero. If the environment already has one of the suite's tools at a different version, install leaves it as-is and reports a conflict rather than replacing it.

Use acquire when you want the tools on the machine now and will choose later which environment uses them; use install when you want the suite ready to run in the environment you're working in. Because install reuses whatever acquire already downloaded, running one after the other does not re-download. Acquired tools show up in igny tool list. To make one already-acquired tool usable in the current environment without downloading anything, bind it with igny tool bind <name> — the inventory-only counterpart to igny tool install. (igny tool install <name> also works and will acquire the tool first if it isn't on the machine yet.)

---

14. Diagnostics

Run human-readable diagnostics — checks core runtime dependencies (Python, Git, Docker, registry readiness) and prints clear status without raw tracebacks:

igny doctor

Machine-readable form for scripts and CI:

igny doctor --json

{
  "ok": true,
  "exit_code": 0,
  "checks": []
}

Both exit non-zero when a critical check fails.

---

15. Registry Cache

Crucible caches the Ayudha tool registry locally. Refresh it:

igny cache sync

Registry synced - 42 tools available

Clear cached registry metadata and downloaded artifact archives:

igny cache clear

Cache cleared

(Cache is already empty if there was nothing to clear.) Neither command needs a workspace.

---

16. Environment Variables Reference

Variable	Purpose
CRUCIBLE_ROOT	Override the visible platform root (tool payloads). Default ~/Crucible/.
IGNYTION_HOME	Override where Crucible stores its own configuration, registry cache, and logs (outside your project tree).
CRUCIBLE_ENV	Force which environment igny run / igny env shell resolve to.
CRUCIBLE_VERSION	Version string reported by igny --version (otherwise dev).
$IGNY_ENV	Set by igny env shell inside the subshell to mark the active environment (read-only signal).

Keep CRUCIBLE_ROOT and IGNYTION_HOME pointed at separate directories.

---

17. Troubleshooting

igny run <tool> says the binary isn't bound. The tool isn't installed in (or bound to) the resolved environment. Find the provider and install it:

igny tool show <binary>      # names the provider + install hint
igny tool install <provider>

igny run can't find your workspace. You can run igny run from anywhere inside your workspace — including a subdirectory; it walks up to locate the workspace automatically, and the tool launches in the folder you're standing in. Run from a directory inside (or at) your workspace, and check where you are with igny status.

A tool runs in one environment but not another. Installing a payload doesn't bind it everywhere. Install it from within the second environment's workspace, or re-bind:

igny tool show <tool>        # see which envs bind it
igny tool install <tool>     # from inside the target workspace

igny env activate refuses a second environment. On the community tier only one environment is active at a time. Deactivate the current one first, or pass --yes to let activation deactivate it for you:

igny env deactivate <current>
# or
igny env activate <new> --yes

After igny env rename, a workspace still shows the old environment. Renames don't auto-patch workspace pointers. Run the repair command the rename warning printed:

igny workspace bind <new-name> --path <workspace-path>

igny tool uninstall kept the payload. That's expected when another environment still binds the tool — it's a notice, not an error. Unbind it from the other environments first if you truly want it gone:

igny tool unbind <tool> --all-envs
igny tool uninstall <tool>

If you intentionally want to remove the payload while leaving non-active environment bindings dangling, use igny tool uninstall <tool> --force.

igny run says a bound tool is not runnable. If files are missing, a normal install usually heals the binding:

igny tool install <tool>

If the files are present but corrupt, repair the payload explicitly:

igny tool install <tool> --repair

igny env delete is refused. You can't delete the active environment, the reserved default, or one a workspace still references. Deactivate / re-bind, then delete.

Network or registry errors during install or cache sync. Confirm connectivity, then run igny doctor — it flags registry readiness and other runtime issues.

---

18. End-to-End Recipes

Recipe A — A fresh simulation project

igny env create sim
igny workspace create uart-soc --path ./uart-soc --env sim
cd uart-soc

igny tool install verilator
igny tool install gtkwave
igny workspace lock

igny run verilator --version
igny status

Recipe B — A firmware build with a cross-compiler

igny env create fw-build
igny workspace create blinky --path ./blinky --env fw-build
cd blinky

igny compiler install riscv-none-elf
igny run riscv-none-elf-gcc -O2 -c main.c -o main.o
igny workspace lock

Recipe C — Reproduce a teammate's project

git clone <project-repo>
cd <project>

igny workspace sync          # installs + binds everything from crucible.lock
igny status                  # confirm tool count and lock state
igny run verilator --version

Recipe D — Work in an interactive shell

cd uart-soc
igny env shell
# inside the subshell, all bound tools are on PATH:
verilator --version
python -c "import cocotb; print(cocotb.__version__)"
exit

---

19. Inspecting Your Installed CLI

This guide covers the stable, supported path. To see exactly what your installed build exposes, ask the CLI directly:

igny --help
igny env --help
igny workspace --help
igny tool --help
igny compiler --help
igny run --help

Each subgroup's --help lists its current options and is always authoritative for the version you have installed.