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 is for the commands users can run successfully in the current beta CLI. It focuses on the stable, practical path for creating a workspace, creating an environment, installing a tool, and running it.
For product information, visit www.ignytion.io.
For support or questions, contact info@ignytion.io.
1. Quick Start
This is the recommended demo and first-use flow.
1.1 One-Line Sequence
igny env create mysim
igny workspace create --path ./chip_design_workspace --env mysim
cd ./chip_design_workspace
igny tool install gtkwave
igny run tool gtkwave
1.2 Step By Step
Create an environment:
igny env create mysim
Create a workspace and bind it to that environment:
igny workspace create --path ./chip_design_workspace --env mysim
Go into the workspace:
cd ./chip_design_workspace
Install gtkwave into the workspace environment:
igny tool install gtkwave
Run gtkwave:
igny run tool gtkwave
1.3 If You Already Created The Workspace First
If the workspace already exists and is pointing at the wrong environment, fix it like this:
cd ./chip_design_workspace
igny env create mysim
igny env use mysim --workspace
igny tool install gtkwave
igny run tool gtkwave
2. 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 ...
3. Environments
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
Use an environment for the current workspace:
igny env use sim --workspace
Delete an inactive environment:
igny env delete sim
4. Workspaces
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.
5. Install And Inspect Tools
Install a tool inside the current workspace:
igny tool install verilator
Install a specific version:
igny tool install fusesoc --version 2.4.5
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
6. Run A Tool
Run a tool bound to the current workspace environment:
igny run tool verilator -- --version
Arguments after -- are passed to the tool.
Interactive tools run in the current terminal session. For example, terminal
tools such as yosys and renode should show their normal banner or prompt,
and GUI tools such as gtkwave should launch normally.
If igny run tool <tool> says the tool is not bound to the current
environment, repair it from inside the workspace that uses that environment:
igny tool install verilator
Examples:
igny run tool gtkwave
igny run tool fusesoc -- --version
igny run tool verilator -- --version
igny run tool yosys
igny run tool renode
7. Lock And Reproduce 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
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.
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 Tools And Run Diagnostics
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
Run human-readable diagnostics:
igny doctor
Run JSON diagnostics:
igny doctor --json
10. Typical User Flow
igny env create 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
11. Use The Installed CLI Surface
This guide intentionally covers the current working CLI path.
If you want to inspect exactly what your installed package exposes, use:
igny env --help
igny workspace --help
igny tool --help
igny run --help