Skip to main content

Igny CLI - Beta Version User Guide

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

This guide shows the common igny commands users need to create environments, create workspaces, install tools, lock tool state, sync a workspace, and run tools or scripts.

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

1. Check The CLI​

Show the installed CLI version:

igny --version

Show available command groups:

igny --help

Common command groups:

igny env ...
igny workspace ...
igny tool ...
igny run ...
igny doctor
igny cache ...

2. Create And Activate An Environment​

Create an environment:

igny env create sim

Create an environment with a stack label:

igny env create sim --stack default

List environments:

igny env list

Activate an environment:

igny env activate sim

Delete an inactive environment:

igny env delete sim

An active environment must be deactivated before it can be deleted. If the release exposes igny env deactivate, use:

igny env deactivate sim

3. Create A Workspace​

Create a workspace in a new directory:

igny workspace create my-chip --path ./my-chip --env sim
cd my-chip

Create a workspace in the current directory:

igny workspace create --env sim

The workspace manifest is:

crucible.toml

The workspace records the selected environment. Tools installed from inside the workspace are bound to that environment.

4. Install Tools​

Install a tool into the machine inventory:

igny tool install verilator

Install a specific version:

igny tool install fusesoc --version 2.4.5

When run inside a workspace, a successful tool install also binds the tool to the workspace-selected environment.

List installed tools:

igny tool list

Check whether a tool is installed:

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

Uninstall an unreferenced tool version:

igny tool uninstall fusesoc 2.4.5

5. Lock A Workspace​

After installing and binding tools inside a workspace, write a lock file:

igny env lock

This creates:

crucible.lock

Commit both workspace files when sharing a reproducible project:

crucible.toml
crucible.lock

6. Reproduce A Workspace​

After cloning a project that contains crucible.toml and crucible.lock, run:

igny workspace sync

This reads the lock file, installs missing tools into the machine inventory, and binds the locked tools to the workspace environment.

7. Run A Tool​

Run a tool bound to the current workspace environment:

igny run tool verilator -- --version

Arguments after -- are passed to the tool.

If the release exposes the environment override option, run a tool with an explicit environment:

igny run tool verilator --env sim -- --version

Library-only packages are not run as tools. Use them from scripts instead.

8. Run A Script​

Run a Python script in the workspace environment context:

igny run script ./scripts/build.py

Pass script arguments after --:

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

9. Discover Available Tools​

List tools known to the bundled or synced registry:

igny list

Sync the registry cache:

igny cache sync

Clear local registry cache data:

igny cache clear

10. Run Diagnostics​

Run human-readable diagnostics:

igny doctor

Run JSON diagnostics:

igny doctor --json

11. Typical Flow​

igny env create sim
igny env activate sim
igny workspace create my-chip --path ./my-chip --env sim
cd my-chip
igny tool install verilator
igny env lock
igny run tool verilator -- --version

To reproduce on another machine:

git clone <project-repo>
cd <project>
igny workspace sync
igny run tool verilator -- --version

12. Current Limitations​

Some command behavior depends on the package version being validated.

  • Native flow execution through igny run flow and igny run sim may not be release-ready in early builds.
  • igny shell may be exposed but not stable in early builds.
  • Tier-limit behavior for active environments must be checked against the package release notes.
  • Some target commands, such as igny env use and igny env deactivate, may be unavailable until the release that ships them.

Use igny --help and command-specific help to confirm what your installed package exposes:

igny env --help
igny workspace --help
igny run --help