> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roll.codes/llms.txt
> Use this file to discover all available pages before exploring further.

# create-roll-codes CLI

> Reference for the starter CLI in this repository that scaffolds a Foundry project wired for roll.codes integration work.

Use the CLI when you want a generated project instead of setting up the dependency wiring by hand.

## Current availability

The CLI source lives in this repository under `packages/create-roll-codes`. Build it locally before using it.

```bash theme={null}
cd packages/create-roll-codes
npm ci
npm run build
```

## Primary command

```bash theme={null}
node /path/to/roll.codes/packages/create-roll-codes/dist/index.js contract <name>
```

## Example

```bash theme={null}
node /path/to/roll.codes/packages/create-roll-codes/dist/index.js contract my-game --yes --skip-install
cd my-game
forge install roll.codes=jarrodwatts/roll.codes@main --no-git
forge install forge-std=foundry-rs/forge-std --no-git
forge build --zksync
forge test --zksync -vvv
```

## Useful flags

| Flag              | Purpose                                            |
| ----------------- | -------------------------------------------------- |
| `--yes`           | Run non-interactively for scripts or agents.       |
| `--dir <path>`    | Write the generated project to a custom directory. |
| `--git-ref <ref>` | Pin the `roll.codes` dependency to a specific ref. |
| `--skip-install`  | Generate files without running `forge install`.    |
| `--force`         | Allow generation in a non-empty directory.         |

## Generated starter files

* `src/DiceDuelConsumer.sol`
* `test/DiceDuelConsumer.t.sol`
* `script/DeployDiceDuelConsumer.s.sol`
* `foundry.toml`
* `remappings.txt`

The generated starter uses the public `IVRFSystem` surface:

* `requestRandomNumberWithTraceId(uint256)`
* `requestFee()`
* `randomNumberCallback(uint256,uint256)`

## When to use the CLI

Choose the CLI when you want:

* the fastest path to a working sample
* a known-good test and deploy scaffold
* a reproducible non-interactive setup flow

If you already have an existing Foundry project, use [Install and setup](/install) instead.

## Related pages

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Follow the end-to-end starter flow after scaffolding.
  </Card>

  <Card title="Install and setup" icon="wrench" href="/install">
    Wire an existing project manually if you do not want a generated starter.
  </Card>

  <Card title="Troubleshooting" icon="life-buoy" href="/faq/troubleshooting">
    Debug install failures, remapping issues, and callback problems.
  </Card>
</CardGroup>