ChipFoundry CLI (`cf-cli`)

A command-line tool to automate the submission of ChipFoundry projects to the SFTP server and manage project results.

Overview

cf-cli is a user-friendly command-line tool for securely submitting your ChipFoundry project files to the official SFTP server and downloading project results. It automatically collects the required files, generates or updates your project configuration, uploads everything to the correct location on the server, and provides tools to view project results and reports.

Installation

Install from PyPI:

pip install chipfoundry-cli
cf --help

Quick Start

For New Projects (Starting from Template)

Clone the template (or create new directory):

git clone https://github.com/chipfoundry/caravel_user_project my_project
cd my_project

Initialize your project (required first step):
```
cf init
```
This creates .cf/project.json with project metadata. Must be run before any other commands.
Set up the project (replaces make setup):
```
cf setup
```
Generate SSH Key (if you don't have one):
```
cf keygen
```
Register your key at https://chipfoundry.io/sftp-registration
Configure your credentials:
```
cf config
```
Upload your project:
```
cf push
```
Download results (when available):
```
cf pull
```
View tapeout report:
```
cf view-tapeout-report
```
Confirm final tapeout (when ready to send GDS to foundry):

cf confirm

For Existing Projects

If you already have a project with a Makefile:

Generate SSH Key (if you don't have one):
```
cf keygen
```
Register your key at https://chipfoundry.io/sftp-registration
Configure your credentials:
```
cf config
```
Initialize your project:
```
cf init
```
Upload your project:
```
cf push
```
Download results (when available):
```
cf pull
```
View tapeout report:
```
cf view-tapeout-report
```
Confirm final tapeout (when ready to send GDS to foundry):
```
cf confirm
```

Project Structure Requirements

Your project directory must contain:

gds/ directory with one of the following:
- user_project_wrapper.gds (for digital projects)
- user_analog_project_wrapper.gds (for analog projects)
- openframe_project_wrapper.gds (for openframe projects)
- Note: Both compressed (.gz) and uncompressed (.gds) files are supported
verilog/rtl/user_defines.v (required for digital/analog)
.cf/project.json (optional; will be created/updated automatically)
- Contains project metadata including submission_state ("Draft" or "Final")

Example:

my_project/
├── gds/
│   └── user_project_wrapper.gds
├── verilog/
│   └── rtl/
│       └── user_defines.v
└── .cf/
    └── project.json

Authentication

The CLI uses SSH key authentication for secure SFTP access:

Default key location: ~/.ssh/chipfoundry-key (generated by cf keygen)
Alternative key: Specify with --sftp-key option
SFTP username: Required and configured via cf config

SFTP Server

Default server: sftp.chipfoundry.io
Username format: firstname-lastname (e.g., john-doe)

Commands

Generate SSH Key

cf keygen [--overwrite]

Generates a new RSA SSH key at ~/.ssh/chipfoundry-key
Displays the public key for registration
Use --overwrite to regenerate an existing key
Next step: Submit the public key to https://chipfoundry.io/sftp-registration

View SSH Key

cf keyview

Displays the current ChipFoundry SSH public key
Useful for viewing your key without generating a new one
Shows the same registration instructions as cf keygen

Configure User Credentials

cf config

Prompts for your SFTP username and key path
Defaults to ~/.ssh/chipfoundry-key
Only needs to be run once per user/machine

Initialize a New Project

cf init [--project-root DIRECTORY]

Important

This command must be run first after cloning a repository. It is required before running:

cf gpio-config
cf harden
cf precheck
cf verify
cf push

If you skip this step, other commands will show an error directing you to run cf init first.

What it does:

Smart defaults: Auto-detects project name from directory and project type from GDS files
Interactive prompts: Shows detected values in prompts for easy acceptance
Creates .cf/project.json with project metadata

Note

GDS hash is generated during push, not init

Setup a ChipFoundry Project

cf setup [OPTIONS]

Replaces make setup - Comprehensive project setup with all dependencies.

Prerequisites:

Must run cf init first - Project initialization is required

What it does:

Initializes project configuration (.cf/project.json)
Syncs with upstream repository
Installs Caravel/Caravel-Lite
Sets up timing scripts
Configures Cocotb testing environment
Installs precheck tools
Pulls Docker images for verification
Runs IPM for dependency management

Key Options:

--only-init: Just create configuration, skip installations
--dry-run: Preview actions without making changes
--pdk TEXT: Specify PDK variant (default: sky130A)
--caravel-lite / --no-caravel-lite: Choose Caravel variant
--skip-caravel, --skip-openlane, --skip-pdk, etc.: Skip specific installations
--repo-owner, --repo-name, --branch: Custom repository source

Examples:

# Full setup (replaces make setup)
cf setup

# Quick configuration only
cf setup --only-init

# Preview what will be installed
cf setup --dry-run

# Custom PDK
cf setup --pdk sky130B

# Skip time-consuming installations
cf setup --skip-openlane --skip-pdk

See also:

Detailed documentation: docs/cf-setup.md
Migration guide: docs/MIGRATION.md

Configure GPIO Settings

cf gpio-config [--project-root DIRECTORY]

Replaces manual editing of verilog/rtl/user_defines.v - Interactive GPIO configuration tool.

Prerequisites:

Must run cf init first - Project initialization is required
GPIO configuration is required before cf precheck or cf verify

What it does:

Presents an interactive form for configuring GPIO pins 5-37 (GPIO 0-4 are fixed system pins)
Shows available GPIO modes in a table with descriptions
Allows selection by number, partial key, or full mode name
Saves configuration to .cf/project.json (as hex values)
Automatically updates verilog/rtl/user_defines.v with the new configuration
Automatically runs gen_gpio_defaults.py to generate GPIO defaults for simulation (if Caravel is installed)

Prerequisites:

Must run cf init first - Project initialization is required
Must be run before cf precheck or cf verify
GPIO configuration is required for verification and precheck to run

GPIO Modes Available:

Management modes: mgmt_input_nopull, mgmt_input_pulldown, mgmt_input_pullup, mgmt_output, mgmt_bidirectional, mgmt_analog
User modes: user_input_nopull, user_input_pulldown, user_input_pullup, user_output, user_bidirectional, user_output_monitored, user_analog

Usage:

Enter a number (1-13) to select a mode from the table
Enter a partial key (e.g., "user_out" matches "user_output")
Enter the full key name (e.g., "user_output")
Press Enter to keep current valid value (invalid values require input)

Examples:

# Configure GPIO settings interactively
cf gpio-config

# Configure for a specific project directory
cf gpio-config --project-root /path/to/project

What gets updated:

.cf/project.json: GPIO configuration stored as hex values (e.g., "5": "13'h1808")
verilog/rtl/user_defines.v: GPIO mode definitions updated (e.g., USER_CONFIG_GPIO_5_INIT)

Note

Invalid modes cannot be saved. All GPIOs must have valid configurations.

Harden a Macro

cf harden [MACRO] [OPTIONS]

Replaces make harden and make <macro_name> - Harden macros using LibreLane/OpenLane.

Prerequisites:

Must run cf init first - Project initialization is required
OpenLane must be installed (via cf setup)

What it does:

Lists available macros in openlane/ directory
Runs the hardening flow (synthesis, placement, routing) for a specific macro
Generates GDS, LEF, and other output files
Supports both Nix and Docker execution environments

Key Options:

--list or no argument: List all available macros
MACRO: Name of macro to harden (e.g., user_proj_example, user_project_wrapper)
--project-root: Specify project directory
--tag: Custom run tag (defaults to timestamp)
--pdk: PDK to use (default: sky130A)
--use-nix: Force use of Nix (fails if Nix not available)
--use-docker: Force use of Docker (fails if Docker not available)
--dry-run: Show configuration without running

Examples:

# List all available macros
cf harden --list

# Harden a specific macro (replaces make user_proj_example)
cf harden user_proj_example

# Harden with custom tag and PDK
cf harden user_proj_example --tag my_run --pdk sky130B

# Preview hardening configuration
cf harden user_proj_example --dry-run

Workflow:

Macro Hardening: Harden individual macros first
```
cf harden user_proj_example
```
Integration: Update openlane/user_project_wrapper/config.json to reference your macros
Wrapper Hardening: Harden the top-level wrapper
```
cf harden user_project_wrapper
```

Output Files:

gds/<macro>.gds - GDSII layout file
lef/<macro>.lef - LEF file for integration
verilog/gl/<macro>.v - Gate-level netlist
spef/<macro>.spef - Parasitic extraction file
sdc/<macro>.sdc - Timing constraints

Run Precheck Validation

cf precheck [OPTIONS]

Replaces make precheck - Run MPW precheck validation on your project.

Prerequisites:

Must run cf init first - Project initialization is required
Must run cf gpio-config first - GPIO configuration is required
Precheck tools must be installed (via cf setup)
PDK must be installed (via cf setup)
Docker must be available

What it does:

Validates your design against MPW (Multi-Project Wafer) requirements
Runs DRC, LVS, and other design rule checks
Ensures your design will fit into the SoC reference design
Generates reports highlighting any violations

Key Options:

--project-root: Specify project directory
--disable-lvs: Skip LVS check, run specific checks only
--checks: Run specific checks (can be specified multiple times)
- Available: license, makefile, default, documentation, consistency, gpio_defines, xor, magic_drc, klayout_feol, klayout_beol, klayout_offgrid, klayout_met_min_ca_density, klayout_pin_label_purposes_overlapping_drawing, klayout_zeroarea
--dry-run: Show command without running

Examples:

# Run all precheck validations (replaces make precheck)
cf precheck

# Run without LVS check
cf precheck --disable-lvs

# Run specific checks only
cf precheck --checks license --checks makefile --checks gpio_defines

# Preview precheck command
cf precheck --dry-run

What gets checked:

License compliance
Makefile structure
GPIO configuration validity
Design consistency
DRC (Design Rule Check)
LVS (Layout vs Schematic)
And more...

Note

Precheck is required before submitting your design for fabrication.

Run Verification Tests

cf verify [TEST] [OPTIONS]

Replaces make verify-<test>-rtl and make verify-<test>-gl - Run Cocotb verification tests.

Prerequisites:

Must run cf init first - Project initialization is required
Must run cf gpio-config first - GPIO configuration is required
Cocotb environment must be set up (via cf setup)
Caravel must be installed (via cf setup)

What it does:

Runs functional verification tests using Cocotb
Supports both RTL and gate-level (GL) simulations
Can run individual tests or all tests
Uses Docker container for consistent test environment

Key Options:

TEST: Name of specific test to run (e.g., counter_la)
--project-root: Specify project directory
--sim: Simulation type - rtl (default) or gl (gate-level)
--list: List all available tests
--all: Run all tests
--tag: Run tests from a specific YAML test list (e.g., user_proj_tests)
--dry-run: Show configuration without running

Examples:

# List all available tests
cf verify --list

# Run a specific test (RTL simulation, replaces make verify-counter_la-rtl)
cf verify counter_la

# Run gate-level simulation (replaces make verify-counter_la-gl)
cf verify counter_la --sim gl

# Run all tests
cf verify --all

# Run all RTL tests
cf verify --all --sim rtl

# Run tests from a specific test list
cf verify --tag user_proj_tests

# Preview verification command
cf verify counter_la --dry-run

Test Types:

RTL Simulation: Tests your RTL design
Gate-Level (GL) Simulation: Tests the synthesized gate-level netlist

Note

Verification tests ensure your design works correctly before hardening and submission.

Push a Project (Upload)

cf push [OPTIONS]

Options:

--project-root: Specify project directory
--force-overwrite: Overwrite existing files on SFTP
--dry-run: Preview what would be uploaded
--sftp-username: Override configured username
--sftp-key: Override configured key path

What happens:

Collects required project files
Auto-detects project type from GDS file
Updates project configuration and GDS hash
Uploads files to SFTP with progress bars
Shows clean, informative output

GDS File Handling:

Both compressed (.gz) and uncompressed (.gds) files are supported
No automatic compression - files are uploaded as-is
Only one version allowed - you cannot have both compressed and uncompressed versions of the same file
Prefers uncompressed files when available
Falls back to compressed files if no uncompressed version is available

Pull Results (Download)

cf pull [--project-name NAME]

Downloads project results from SFTP server
Saves to sftp-output/<project_name>/
Automatically updates your local .cf/project.json with the pulled version

Creates the expected directory structure:

sftp-output/
└── <project_name>/
    ├── config/
    │   └── project.json
    └── consolidated_reports/
        └── consolidated_report.html

Confirm Final Tapeout

cf confirm [OPTIONS]

Confirms your final tapeout by setting submission_state to "Final"
Uploads only the project.json to the SFTP server (not the entire project)
Use this when you're ready to send your current GDS file to the foundry for tapeout processing
Options:
- --project-root: Specify project directory
- --project-name: Override project name
- --sftp-username: Override configured username
- --sftp-key: Override configured key path

Important

This command confirms that your current GDS file is ready to be sent to the foundry for tapeout. Only run this when you are completely satisfied with your design and ready for final tapeout processing. This action cannot be easily undone.

View Tapeout Report

cf view-tapeout-report [--project-name NAME] [--report-path PATH]

Opens the consolidated tapeout report in your default browser
Auto-detects project name from .cf/project.json if available
Looks for report at sftp-output/<project_name>/consolidated_reports/consolidated_report.html
Options:
- --project-name: Specify project name manually
- --report-path: Provide direct path to HTML report file

Check Status

cf status

Lists all your projects on the SFTP server
Shows which projects have input files and/or results
Displays project status in a clean table format

Repository Management

Update Repository Files

cf repo update [OPTIONS]

Updates local project files from the upstream GitHub repository
Fetches configuration from .cf/repo.json in the specified repository and branch
Downloads and overwrites local files based on the changes list in the configuration
Saves configuration locally to .cf/repo.json for reference

Options:

--project-root: Specify project directory (defaults to current directory)
--repo-owner: GitHub repository owner (default: chipfoundry)
--repo-name: GitHub repository name (default: caravel_user_project)
--branch: Branch name containing the repo.json file (default: main)
--dry-run: Preview changes without updating files

What happens:

Fetches .cf/repo.json from the specified GitHub repository and branch
Downloads and saves the configuration file locally to .cf/repo.json
Downloads and overwrites each file listed in the changes array
Provides detailed feedback on success/failure of each file update

Example:

# Preview what would be updated
cf repo update --dry-run
# Output:
# Files that would be updated:
#   • .cf/repo.json (configuration file)
#   • README.md
#   • Makefile
#   • openlane/Makefile

# Update files from upstream
cf repo update
# Output:
# Update results:
# ✓ Updated: .cf/repo.json
# ✓ Updated: README.md
# ✓ Updated: Makefile
# ✓ Updated: openlane/Makefile
# Successfully updated 4 file(s)
# All files updated successfully!

Use cases:

Keep your project up-to-date with upstream changes
Apply bug fixes and improvements from the template repository
Sync configuration changes from the upstream project
Maintain consistency with the latest project structure

Submission Workflow and States

The CLI tracks your project submission state through the submission_state field in project.json:

Project States

"Draft" - Initial state when you run cf init
- Project is ready for development and testing
- You can push updates multiple times
- Project is not yet ready for tapeout processing
"Final" - Confirmed state when you run cf confirm
- GDS file is ready to be sent to the foundry for tapeout
- No further changes should be made to the design
- Only the project.json is uploaded (not the full project)

Recommended Workflow

Development Phase:

cf init          # Creates project with submission_state: "Draft"
cf push          # Upload project files (state remains "Draft")
# ... make changes to your project ...
cf push          # Upload updated files (state remains "Draft")

Review Phase (Optional):

cf pull          # Download results for review (if available)
cf view-tapeout-report  # Review the tapeout report (if available)

Final Tapeout Confirmation:

cf confirm       # Confirm current GDS file is ready for foundry tapeout

Important

Only run cf confirm when you are completely satisfied with your GDS file and ready to send it to the foundry for tapeout processing. This action cannot be easily undone.

How the GDS Hash Works

The user_project_wrapper_hash in .cf/project.json is automatically generated and updated during push
The hash is calculated from the actual GDS file being uploaded
This ensures the hash always matches the file you are submitting
You do not need to manage or update the hash manually
The hash is NOT generated during init because the GDS file may not exist or may change before submission

What Happens When You Run `cf push`?

File Collection:
- Checks for required GDS and Verilog files
- Auto-detects project type (digital, analog, openframe) based on GDS file name
- Supports both compressed and uncompressed GDS files
Configuration:
- Creates or updates .cf/project.json
- Updates the GDS hash and any CLI-overridden fields
SFTP Upload:
- Connects to the SFTP server securely
- Creates project directory structure
- Uploads files with progress indicators
- Shows clean, minimal output
Success:
- Displays confirmation with project location

What Happens When You Run `cf pull`?

Connection:
- Connects to SFTP server securely
- Shows clean connection status
Download:
- Downloads all project results recursively
- Shows professional download progress
- Saves to sftp-output/<project_name>/
Config Update:
- Automatically updates your local .cf/project.json with the pulled version
- No manual steps required
Success:
- Shows confirmation of downloaded files and updated config

Examples

Basic Workflow

# Generate SSH key and register it
cf keygen
# Copy the displayed key to https://chipfoundry.io/sftp-registration

# Configure your account
cf config
# Enter: john-doe
# Enter: (press Enter for default key)

# Initialize project (in your project directory)
cf init
# Project name (detected: my_awesome_project): 
# Project type (digital/analog/openframe) (detected: digital): 

# Upload your project
cf push
# Connecting to sftp.chipfoundry.io...
# Uploading project.json ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
# Uploading user_project_wrapper.gds ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
# ✓ Uploaded to incoming/projects/my_awesome_project

# Later, download results
cf pull
# ✓ Connected to sftp.chipfoundry.io
# Downloading project results from outgoing/results/my_awesome_project...
# ✓ All files downloaded to sftp-output/my_awesome_project
# ✓ Project config automatically updated

# Review the tapeout report (if available)
cf view-tapeout-report
# ✓ Opened tapeout report in browser: sftp-output/my_awesome_project/consolidated_reports/consolidated_report.html

# When ready, confirm final tapeout (sends GDS to foundry)
cf confirm
# ✓ Updated project.json with submission_state = Final
# ✓ Confirmed project submission: my_awesome_project
# ✓ Uploaded project.json to incoming/projects/my_awesome_project/.cf/project.json

Advanced Usage

# Preview what would be uploaded
cf push --dry-run

# Force overwrite existing files
cf push --force-overwrite

# Use different project root
cf push --project-root /path/to/project

# Pull results for specific project
cf pull --project-name other_project

# View report for specific project
cf view-tapeout-report --project-name other_project

# Confirm final tapeout for specific project
cf confirm --project-name other_project

# View custom report file
cf view-tapeout-report --report-path /path/to/custom_report.html

# Check project status
cf status

GDS File Examples

# Uncompressed GDS file (preferred)
gds/user_project_wrapper.gds

# Compressed GDS file (also supported)
gds/user_project_wrapper.gds.gz

# ❌ INVALID: Both files exist - this will cause an error
gds/user_project_wrapper.gds      # ← Choose ONE version only
gds/user_project_wrapper.gds.gz   # ← Remove this one

Troubleshooting

Missing files:
- The tool will error out if required files are missing or if more than one GDS type is present
Authentication errors:
- Run cf keygen to generate a new key
- Ensure your key is registered at https://chipfoundry.io/sftp-registration
- Check your username with cf config
SFTP errors:
- Check your network connection
- Verify your credentials with cf config
Project type detection:
- Only one of the recognized GDS files should be present in your gds/ directory
- Both compressed and uncompressed versions of the same type are supported
- Important: You cannot have both compressed (.gz) and uncompressed (.gds) versions of the same file - the tool will error out and ask you to remove one
Report viewing errors:
- Ensure you've run cf pull first to download the report
- Check that the report exists at the expected location
- Use --report-path to specify a custom report location
Repository update errors:
- Check your internet connection
- Verify the repository and branch exist
- Use --dry-run to preview changes before applying them
- Check that the .cf/repo.json file exists in the upstream repository
ModuleNotFoundError:
- Upgrade the CLI: pip install --upgrade chipfoundry-cli

Support

For help, contact info@chipfoundry.io or visit chipfoundry.io
For bug reports or feature requests, open an issue on GitHub

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.github/workflows		.github/workflows
chipfoundry_cli		chipfoundry_cli
docs		docs
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
versions.json		versions.json

License

chipfoundry/cf-cli

Folders and files

Latest commit

History

Repository files navigation

ChipFoundry CLI (cf-cli)

Overview

Installation

Quick Start

For New Projects (Starting from Template)

For Existing Projects

Project Structure Requirements

Authentication

SFTP Server

Commands

Generate SSH Key

View SSH Key

Configure User Credentials

Initialize a New Project

Setup a ChipFoundry Project

Configure GPIO Settings

Harden a Macro

Run Precheck Validation

Run Verification Tests

Push a Project (Upload)

Pull Results (Download)

Confirm Final Tapeout

View Tapeout Report

Check Status

Repository Management

Update Repository Files

Submission Workflow and States

Project States

Recommended Workflow

How the GDS Hash Works

What Happens When You Run cf push?

What Happens When You Run cf pull?

Examples

Basic Workflow

Advanced Usage

GDS File Examples

Troubleshooting

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

ChipFoundry CLI (`cf-cli`)

What Happens When You Run `cf push`?

What Happens When You Run `cf pull`?

Packages