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

# sf init

> Create a fine-tuning repository with the installed CLI

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
uv tool install starforge-core     # or: pip install starforge-core
sf init my-lab
cd my-lab
```

`sf init` scaffolds a self-contained project on your machine. The CLI comes from PyPI — you do not
clone the platform repository to get it, and you do not clone it to use it.

That project is also one **project** in console terms: `name` in `starforge.yaml` is what groups
every run of every experiment in it.

## Install the CLI

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
uv tool install starforge-core
# or, without uv
pip install starforge-core
```

`uv tool install` is the recommended one. It puts `sf` in its own environment, so it cannot
collide with the packages of whatever project you happen to be standing in — and `sf update`
can upgrade it. Installed with `pip` into a system Python, `sf update` refuses and tells you to
reinstall with `uv tool`, because upgrading there could disturb other tools.

Verify:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf --help
sf --install-completion    # optional: shell completion
```

Upgrade with `sf update`, which detects how it was installed and uses the right command.
Source lives in `core/starforge/cli/`.

## Create a repository

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf init my-lab                 # interactive: directory / name / git
sf init my-lab --yes           # non-interactive, all defaults
sf init . --name my-lab --yes  # initialize the current directory
```

Layout:

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
my-lab/
├── starforge.yaml     # repo marker + project name (the only signal `sf` uses to find the root)
├── experiments/       # `sf new` creates experiments here
├── configs/           # official bases + model fragments (yours to edit or pin)
├── common/            # shared repository code (data scripts / envs / rewards)
├── .gitignore
└── README.md
```

The platform entrypoint is **neither written into the project nor uploaded by the CLI**. The CLI packages only the experiment, `common/`, and `configs/`; after admission, the console injects a content-addressed Job Capsule (manifest, bootstrap, and PEX runner).

## Project discovery

Commands that need a project (`sf new` / `submit` / `ls` / `validate` …) walk up from the current directory looking for `starforge.yaml`, the same way git finds a repository root.

| Method                              | When                                             |
| ----------------------------------- | ------------------------------------------------ |
| `cd my-lab && sf …`                 | Normal: run inside the project or a subdirectory |
| `SF_REPO_ROOT=/path/to/my-lab sf …` | CI / scripts: set explicitly, no `cd`            |

`sf login` / `logout` / `status` are global and do not require a project.

## Next steps

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
cd my-lab
sf login --server https://<your StarForge domain>
sf new my-grpo --method nemo-rl/grpo
sf submit my-grpo --profile h200:8
```

## `sf init`

Create a StarForge project

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf init [DIRECTORY] [options]
```

| Argument    | Description                                                                          |
| ----------- | ------------------------------------------------------------------------------------ |
| `DIRECTORY` | The repo directory (asked interactively when omitted; . means the current directory) |

| Option        | Description                                                             |
| ------------- | ----------------------------------------------------------------------- |
| `--name`      | Project name, written into starforge.yaml (default: the directory name) |
| `--no-git`    | Do not initialise a git repository                                      |
| `--yes`, `-y` | Non-interactive: take every default                                     |