# Create FHEVM Example CLI

{% hint style="success" %}
**🚀 One Command. Full Privacy. Zero Config.**

Scaffold production-ready FHEVM projects in seconds. Pre-configured Hardhat, encrypted types, and comprehensive tests included.
{% endhint %}

***

## ⚡ Quick Start

Get started in under 30 seconds with our interactive wizard:

{% tabs %}
{% tab title="npm" %}

```bash
npx create-fhevm-example
```

{% endtab %}

{% tab title="yarn" %}

```bash
yarn create fhevm-example
```

{% endtab %}

{% tab title="pnpm" %}

```bash
pnpm create fhevm-example
```

{% endtab %}

{% tab title="bun" %}

```bash
bunx create-fhevm-example
```

{% endtab %}
{% endtabs %}

![🎬 Watch the CLI in action — scaffold a project in seconds!](https://i.ibb.co/PvtZSQyd/create-fhevm.gif)

***

## 🎯 What You Get

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><strong>⚡ Zero Configuration</strong></td><td>Pre-configured <code>hardhat.config.ts</code>, FHE keys, network settings, and environment variables. Just run and build.</td><td></td></tr><tr><td><strong>📚 33+ Ready Examples</strong></td><td>From "Hello World" counters to advanced blind auctions and confidential tokens. Each with full test coverage.</td><td></td></tr><tr><td><strong>🔌 Plug &#x26; Play</strong></td><td>Create new projects OR inject FHE capabilities into your existing Hardhat projects with <code>--add</code> mode.</td><td></td></tr></tbody></table>

***

## 🎮 Three Powerful Modes

Choose the workflow that fits your needs:

### 1️⃣ Single Example Mode

{% hint style="info" %}
**Perfect for:** Learning a specific FHE concept step-by-step.
{% endhint %}

```bash
# Interactive selection
npx create-fhevm-example

# Or directly specify the example
npx create-fhevm-example blind-auction
```

<details>

<summary>📋 What gets created?</summary>

A minimal, focused project with just one example:

```
my-blind-auction/
├── 📄 contracts/BlindAuction.sol    # The FHE smart contract
├── 🧪 test/BlindAuction.ts          # Full test suite
├── ⚙️ hardhat.config.ts             # Pre-configured for Zama
├── 📦 package.json                  # All dependencies included
└── 🔐 .env.example                  # Environment template
```

</details>

***

### 2️⃣ Category Bundle Mode

{% hint style="info" %}
**Perfect for:** Exploring a domain like Gaming, OpenZeppelin, or Advanced patterns.
{% endhint %}

```bash
# Download all 5 Advanced examples at once
npx create-fhevm-example --category advanced
```

**Available Categories:**

| Category             | Examples | Description                                                      |
| -------------------- | :------: | ---------------------------------------------------------------- |
| 🎓 **Basic**         |    11    | Fundamentals: counters, encryption, decryption                   |
| 💡 **Concepts**      |     8    | Access control, handles, input proofs, edge cases, anti-patterns |
| 🎮 **Gaming**        |     4    | Poker, lottery, rock-paper-scissors, blackjack                   |
| 🏛️ **OpenZeppelin** |     5    | ERC7984, wrappers, swaps, vesting                                |
| 🎯 **Advanced**      |     6    | Blind auction, escrow, voting, KYC, payroll, order book          |

***

### 3️⃣ Smart Injection Mode (`--add`)

{% hint style="warning" %}
**Requirement:** Run this inside an existing Hardhat project directory.
{% endhint %}

Already have a project? Upgrade it to FHE in one command:

```bash
cd my-existing-project
npx create-fhevm-example --add
```

**What happens:**

1. ✅ Detects your Hardhat configuration
2. ✅ Adds `@fhevm/solidity` and `@fhevm/hardhat-plugin`
3. ✅ Updates `hardhat.config.ts` with FHE imports
4. ✅ Injects a sample contract and test of your choice

![🔧 Adding FHE to an existing Hardhat project](https://i.ibb.co/LXjWHvH0/add.gif)

***

## ⌨️ CLI Options

| Option              | Description                           |
| ------------------- | ------------------------------------- |
| `--example <name>`  | Create a single example project       |
| `--category <name>` | Create a category project             |
| `--add`             | Add FHEVM to existing Hardhat project |
| `--target <dir>`    | Target directory for --add mode       |
| `--output <dir>`    | Output directory                      |
| `--help`            | Show help message                     |

***

## 🏗️ Project Structure

Every scaffolded project follows this clean, minimal structure:

```
my-fhevm-project/
│
├── 📂 contracts/           # Solidity contracts
│   └── MyContract.sol      # Your FHE-enabled contract
│
├── 📂 test/                # TypeScript tests
│   ├── types.ts            # Shared type definitions
│   └── MyContract.ts       # Mocha/Chai test suite
│
├── ⚙️ hardhat.config.ts    # Hardhat + FHEVM configuration
├── 📦 package.json         # Dependencies and scripts
├── 📄 .env.example         # Environment variable template
└── 📖 README.md            # Project-specific documentation
```

***

## 🎬 Next Steps

After scaffolding, get your project running:

{% stepper %}
{% step %}

#### Install Dependencies

```bash
npm install
```

{% endstep %}

{% step %}

#### Compile Contracts

```bash
npm run compile
```

{% endstep %}

{% step %}

#### Run Tests

```bash
npm run test
```

{% endstep %}

{% step %}

#### Start Building! 🚀

Open `contracts/` and start writing your privacy-preserving logic!
{% endstep %}
{% endstepper %}

***

## ❓ Frequently Asked Questions

<details>

<summary><strong>Does this work with existing Hardhat projects?</strong></summary>

Yes! Use the `--add` flag inside your project directory. The CLI will detect your Hardhat setup and inject FHE dependencies automatically.

```bash
cd my-existing-project
npx create-fhevm-example --add
```

</details>

<details>

<summary><strong>Do I need to install anything globally?</strong></summary>

No! Just use `npx` (comes with Node.js). The CLI runs directly without any global installation.

</details>

<details>

<summary><strong>What Node.js version is required?</strong></summary>

Node.js **v20.0.0** or higher is required. We recommend using the latest LTS version.

</details>

<details>

<summary><strong>Can I use this offline?</strong></summary>

Yes! All example files are bundled in the package. Scaffolding works fully offline — only `npm install` requires internet to download dependencies.

</details>

<details>

<summary><strong>How do I run tests after scaffolding?</strong></summary>

Simply run these commands in your new project:

```bash
npm install
npm run compile
npm run test
```

</details>

<details>

<summary><strong>What networks are supported?</strong></summary>

Projects are pre-configured for:

* **Local** (Hardhat Network with FHEVM mock)
* **Zama Devnet** (Sepolia-based testnet)

You can add more networks in `hardhat.config.ts`.

</details>

***

## 📚 Learn More

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>📖 FHEVM Documentation</strong></td><td>Deep dive into Fully Homomorphic Encryption on the blockchain.<br><a href="https://docs.zama.org/protocol/">docs.zama.org/protocol/</a></td></tr><tr><td><strong>💻 GitHub Repository</strong></td><td>Star us, report issues, or contribute!<br><a href="https://github.com/NecipAkgz/fhevm-example-factory">github.com/NecipAkgz/fhevm-example-factory</a></td></tr></tbody></table>

{% hint style="info" %}
**Need Help?** Join the [Zama Discord](https://discord.gg/zama) community for support and discussions!
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://necips-organization-1.gitbook.io/fhevm-example-factory/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.