Metadata-Version: 2.1
Name: chipfoundry-cli
Version: 2.0.0
Summary: CLI tool to automate ChipFoundry project submission to SFTP server
Home-page: https://chipfoundry.io
License: Apache-2.0
Author: ChipFoundry
Author-email: marwan.abbas@chipfoundry.io
Requires-Python: >=3.8.1,<4.0
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: cf-ipm
Requires-Dist: click (>=8.0.0,<9)
Requires-Dist: httpx (>=0.24.0,<1.0)
Requires-Dist: paramiko (>=3.0.0,<4)
Requires-Dist: rich (>=13,<14)
Requires-Dist: textual (>=0.40.0,<1)
Requires-Dist: toml (>=0.10,<1.0)
Project-URL: Repository, https://github.com/chipfoundry/cf-cli
Description-Content-Type: text/markdown

# ChipFoundry CLI (`cf-cli`)

[![PyPI version](https://img.shields.io/pypi/v/chipfoundry-cli?color=blue)](https://badge.fury.io/py/chipfoundry-cli)
[![PyPI downloads](https://img.shields.io/pypi/dm/chipfoundry-cli.svg)](https://pypi.org/project/chipfoundry-cli/)

A command-line tool for managing ChipFoundry ASIC projects — from authentication and project setup to SFTP submission and platform sync.

---

## Overview

`cf-cli` is a command-line tool that integrates with the ChipFoundry platform for end-to-end project management. It handles browser-based authentication, project registration, SFTP file transfers, and platform synchronization. When you push or pull, the CLI uploads your files via SFTP and syncs project metadata (GDS hash, version, project ID, slot number) with the platform.

---

## Installation

Install from PyPI:

```bash
pip install chipfoundry-cli
cf --help
```

---

## Quick Start

### For New Projects

1. **Log in to the platform**:
   ```bash
   cf login
   ```

2. **Clone the template** (or create new directory):
   ```bash
   git clone https://github.com/chipfoundry/caravel_user_project my_project
   cd my_project
   ```

3. **Initialize your project** (registers on platform and selects shuttle):
   ```bash
   cf init
   ```

4. **Set up the project** (replaces `make setup`):
   ```bash
   cf setup
   ```

5. **Generate SSH Key** (if you don't have one):
   ```bash
   cf keygen
   ```

6. **Register your key** at [https://platform.chipfoundry.io/ssh-key](https://platform.chipfoundry.io/ssh-key)

7. **Configure SFTP credentials**:
   ```bash
   cf config
   ```

8. **Upload your project** (SFTP + platform sync):
   ```bash
   cf push
   ```

9. **Download results** (when available):
   ```bash
   cf pull
   ```

10. **View tapeout report**:
    ```bash
    cf view-tapeout-report
    ```

11. **Confirm final tapeout** (when ready to send GDS to foundry):
    ```bash
    cf confirm
    ```

### For Existing Projects

If you already have a project directory with GDS files:

1. **Log in and set up SFTP**:
   ```bash
   cf login
   cf keygen        # if you don't have an SSH key
   cf config        # set SFTP username and key path
   ```
   Register your key at [https://platform.chipfoundry.io/ssh-key](https://platform.chipfoundry.io/ssh-key)

2. **Initialize and link to the platform**:
   ```bash
   cf init          # creates .cf/project.json and registers on platform
   ```
   Or, if the project already exists on the platform:
   ```bash
   cf init          # creates .cf/project.json locally
   cf link          # links to existing platform project
   ```

3. **Upload, download, and confirm**:
   ```bash
   cf push          # upload files + sync with platform
   cf pull          # download results + view review notes
   cf confirm       # confirm final tapeout
   ```

---

## 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

### Platform Authentication

The CLI uses browser-based login for platform access:

```bash
cf login     # opens browser to authenticate, stores API key
cf whoami    # show current user
cf logout    # clear stored credentials
```

Credentials are stored in `~/.chipfoundry-cli/config.toml`.

### SFTP Authentication

SFTP file transfers use SSH key authentication:

- **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

```bash
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://platform.chipfoundry.io/ssh-key](https://platform.chipfoundry.io/ssh-key)

### View SSH Key

```bash
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 SFTP Credentials

```bash
cf config
```

- Prompts for your SFTP username and key path
- Defaults to `~/.ssh/chipfoundry-key`
- Credentials are saved to `~/.chipfoundry-cli/config.toml`
- Only needs to be run once per user/machine

### Platform Login

```bash
cf login
```

- Opens your default browser to the platform login page
- After authenticating, the CLI automatically receives your API key
- Required before `cf init`, `cf link`, `cf push`, `cf pull`, `cf confirm`

### Check Current User

```bash
cf whoami
```

- Displays the currently authenticated user (name and email)

### Logout

```bash
cf logout
```

- Removes your stored API key from the local config

### Initialize a New Project

```bash
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
- **Shuttle selection**: Prompts to select an available shuttle (sorted by nearest deadline)
- **Platform registration**: Creates the project on the platform and links it automatically
- Creates `.cf/project.json` with project metadata

> [!NOTE]
> GDS hash is generated during `push`, not `init`

### Link an Existing Project

```bash
cf link
```

- Lists your platform projects and prompts you to select one
- Stores the `platform_project_id` in `.cf/project.json`
- Required for `cf push` and `cf pull` to sync with the platform
- Use this when you have a local project and an existing platform project to connect them

### Unlink a Project

```bash
cf unlink
```

- Removes the platform link from the current project
- The project remains on the platform but push/pull will no longer sync

### Setup a ChipFoundry Project

```bash
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:**
1. Initializes project configuration (`.cf/project.json`)
2. Syncs with upstream repository
3. Installs Caravel/Caravel-Lite
4. Sets up timing scripts
5. Configures Cocotb testing environment
6. Installs precheck tools
7. Pulls Docker images for verification
8. 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:**
```bash
# 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](docs/cf-setup.md)
- Migration guide: [docs/MIGRATION.md](docs/MIGRATION.md)

### Configure GPIO Settings

```bash
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:**
1. Presents an interactive form for configuring GPIO pins 5-37 (GPIO 0-4 are fixed system pins)
2. Shows available GPIO modes in a table with descriptions
3. Allows selection by number, partial key, or full mode name
4. Saves configuration to `.cf/project.json` (as hex values)
5. Automatically updates `verilog/rtl/user_defines.v` with the new configuration
6. 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:**
```bash
# 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

```bash
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:**
1. Lists available macros in `openlane/` directory
2. Runs the hardening flow (synthesis, placement, routing) for a specific macro
3. Generates GDS, LEF, and other output files
4. 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:**
```bash
# 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:**
1. **Macro Hardening**: Harden individual macros first
   ```bash
   cf harden user_proj_example
   ```

2. **Integration**: Update `openlane/user_project_wrapper/config.json` to reference your macros

3. **Wrapper Hardening**: Harden the top-level wrapper
   ```bash
   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

```bash
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:**
1. Validates your design against MPW (Multi-Project Wafer) requirements
2. Runs DRC, LVS, and other design rule checks
3. Ensures your design will fit into the SoC reference design
4. 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:**
```bash
# 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

```bash
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:**
1. Runs functional verification tests using Cocotb
2. Supports both RTL and gate-level (GL) simulations
3. Can run individual tests or all tests
4. 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:**
```bash
# 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)

```bash
cf push [OPTIONS]
```

**Prerequisites:** `cf login`, `cf link` (or `cf init`), `cf config`

**Options:**
- `--project-root`: Specify project directory
- `--force-overwrite`: Overwrite existing files on SFTP
- `--submit`: Submit the project for review after upload
- `--dry-run`: Preview what would be uploaded
- `--sftp-username`: Override configured username
- `--sftp-key`: Override configured key path

**What happens:**
1. Verifies the project is linked to the platform and you are logged in
2. Collects required project files
3. Auto-detects project type from GDS file
4. Updates project configuration and GDS hash
5. Uploads files to SFTP with progress bars
6. Syncs `project.json` data to the platform (GDS hash, version, project ID, slot number)
7. If `--submit` is used, submits the project for admin review

**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)

```bash
cf pull [--project-name NAME]
```

**Prerequisites:** `cf login`, `cf link` (or `cf init`), `cf config`

- Downloads project results from SFTP server
- Saves to `sftp-output/<project_name>/`
- **Automatically updates** your local `.cf/project.json` with the pulled version (preserving the platform link)
- **Syncs with the platform** and displays admin review notes if your project has been reviewed
- Creates the expected directory structure:
  ```
  sftp-output/
  └── <project_name>/
      ├── config/
      │   └── project.json
      └── consolidated_reports/
          └── consolidated_report.html
  ```

### Confirm Final Tapeout

```bash
cf confirm [OPTIONS]
```

**Prerequisites:** `cf login`, `cf link` (or `cf init`), `cf config`

- **Confirms your final tapeout** by setting `submission_state` to "Final"
- **Uploads the project.json** to the SFTP server and **confirms on the platform**
- **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

```bash
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

```bash
cf status
```

- Shows project status from the platform, including shuttle details and deadlines
- Lists projects on the SFTP server with input/output status
- Displays project status in a clean table format

### Repository Management

#### Update Repository Files

```bash
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:**
1. Fetches `.cf/repo.json` from the specified GitHub repository and branch
2. Downloads and saves the configuration file locally to `.cf/repo.json`
3. Downloads and overwrites each file listed in the `changes` array
4. Provides detailed feedback on success/failure of each file update

**Example:**
```bash
# 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

1. **Setup Phase:**
   ```bash
   cf login         # Authenticate with the platform
   cf keygen        # Generate SSH key (if needed)
   cf config        # Set SFTP credentials
   cf init          # Initialize project, register on platform, select shuttle
   ```

2. **Development Phase:**
   ```bash
   cf push          # Upload files + sync with platform (state remains "Draft")
   # ... make changes to your project ...
   cf push --force-overwrite  # Upload updated files
   ```

3. **Review Phase:**
   ```bash
   cf pull          # Download results + view admin review notes
   cf view-tapeout-report  # Review the tapeout report (if available)
   ```

4. **Final Tapeout Confirmation:**
   ```bash
   cf confirm       # Confirm on platform, send GDS to foundry
   ```

> [!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`?

1. **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**

2. **Configuration:**
   - Creates or updates `.cf/project.json`
   - Updates the GDS hash and any CLI-overridden fields

3. **SFTP Upload:**
   - Connects to the SFTP server securely
   - Creates project directory structure
   - Uploads files with progress indicators

4. **Platform Sync:**
   - Sends the full `project.json` to the platform
   - Updates GDS hash, project version, project ID, and slot number
   - Records the push timestamp on the platform

5. **Success:**
   - Displays confirmation with project location and sync status

---

## What Happens When You Run `cf pull`?

1. **Connection:**
   - Connects to SFTP server securely
   - Shows clean connection status

2. **Download:**
   - Downloads all project results recursively
   - Shows professional download progress
   - Saves to `sftp-output/<project_name>/`

3. **Config Update:**
   - **Automatically merges** the pulled `project.json` with your local version (preserving the platform link)

4. **Platform Sync:**
   - Sends the updated `project.json` to the platform
   - Records the pull timestamp on the platform
   - Fetches and displays any admin review notes

5. **Success:**
   - Shows confirmation of downloaded files, sync status, and review notes

---

## Examples

### Basic Workflow

```bash
# Generate SSH key and register it
cf keygen
# Copy the displayed key to https://platform.chipfoundry.io/ssh-key

# 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

```bash
# 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

```bash
# 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

- **Platform authentication errors:**
  - Run `cf login` to re-authenticate
  - Run `cf whoami` to verify your login status

- **SFTP authentication errors:**
  - Run `cf keygen` to generate a new key
  - Ensure your key is registered at [https://platform.chipfoundry.io/ssh-key](https://platform.chipfoundry.io/ssh-key)
  - Check your username with `cf config`

- **"Project is not linked to the platform":**
  - Run `cf link` to connect this project to a platform project
  - Or run `cf init` to create a new platform project

- **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](https://chipfoundry.io)
- For bug reports or feature requests, open an issue on [GitHub](https://github.com/chipfoundry/cf-cli)

