Metadata-Version: 2.1
Name: chipfoundry-cli
Version: 1.0.5
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.0
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: click (>=8.0.0,<9)
Requires-Dist: paramiko (>=3.0.0,<4)
Requires-Dist: rich (>=13,<14)
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 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:

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

---

## Quick Start

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

2. **Register your key** at [https://chipfoundry.io/sftp-registration](https://chipfoundry.io/sftp-registration)

3. **Configure your credentials**:
   ```bash
   cf config
   ```

4. **Initialize your project**:
   ```bash
   cf init
   ```

5. **Upload your project**:
   ```bash
   cf push
   ```

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

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

---

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

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

```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://chipfoundry.io/sftp-registration](https://chipfoundry.io/sftp-registration)

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

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

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

```bash
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:**
1. Collects required project files
2. Auto-detects project type from GDS file
3. Updates project configuration and GDS hash
4. Uploads files to SFTP with progress bars
5. 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)

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

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

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

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
   - Shows clean, minimal output

4. **Success:**
   - Displays confirmation with project location

---

## 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 updates** your local `.cf/project.json` with the pulled version
   - No manual steps required

4. **Success:**
   - Shows confirmation of downloaded files and updated config

---

## Examples

### Basic Workflow

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

# View the tapeout report
cf view-tapeout-report
# ✓ Opened tapeout report in browser: sftp-output/my_awesome_project/consolidated_reports/consolidated_report.html
```

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

# 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

- **Authentication errors:**
  - Run `cf keygen` to generate a new key
  - Ensure your key is registered at [https://chipfoundry.io/sftp-registration](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

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

