chipfoundry-cli

ChipFoundry CLI (cf-cli)

A command-line tool to automate the submission of ChipFoundry projects to the SFTP server.

Overview

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

Installation

Install from PyPI:

pip install chipfoundry-cli
cf --help

Quick Start

• 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
  

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)
• verilog/rtl/user_defines.v (required for digital/analog)
• .cf/project.json (optional; will be created/updated automatically)

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]

• 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

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

Pull Results

cf pull [--project-name NAME]

• Downloads project results from SFTP
• Saves to sftp-output/<project_name>/
• Shows download progress for each 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

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

• 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

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

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

# Check project status
cf status

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

• ModuleNotFoundError:

  • Upgrade the CLI: pip install --upgrade chipfoundry-cli

Support

• For help, contact [e-mail] or visit chipfoundry.io
• For bug reports or feature requests, open an issue on GitHub