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

> 用安装好的 CLI 创建微调仓库

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

`sf init` 在你的机器上生成一个自包含的项目。CLI 来自 PyPI——
你不需要 clone 平台仓库来获得它，也不需要 clone 它来使用它。

这个项目同时也是控制台意义上的一个**项目**：`starforge.yaml` 里的 `name`
就是把它里面每个实验的每次 run 归到一起的那个名字。

## 安装 CLI

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
uv tool install starforge-core
# 或者，没有 uv 时
pip install starforge-core
```

推荐 `uv tool install`。它把 `sf` 装进独立环境，不会和你当前所在项目的依赖打架，而且 `sf update`
能升级它。如果用 `pip` 装进系统 Python，`sf update` 会拒绝升级并提示你改用 `uv tool` 重装——
因为在那里升级可能影响系统上的其他工具。

验证：

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf --help
sf --install-completion    # 可选：shell 补全
```

升级：`sf update`，它会检测安装方式并选用对应的命令。源码在 `core/starforge/cli/`。

## 创建仓库

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf init my-lab                 # 交互：目录 / 项目名 / 是否 git
sf init my-lab --yes           # 非交互，全部取默认
sf init . --name my-lab --yes  # 在当前目录初始化
```

生成的布局：

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
my-lab/
├── starforge.yaml     # 仓库标记 + 项目名（sf 发现仓库根的唯一依据）
├── experiments/       # sf new 在此创建实验
├── configs/           # 官方基底 + 模型片段（可改、可 pin）
├── common/            # 项目共享代码（数据脚本 / 环境 / 奖励）
├── .gitignore
└── README.md
```

平台入口**不落地到仓库，也不由 CLI 上传**。CLI 只打包实验、`common/` 与 `configs/`；Console 准入后注入内容寻址 Job Capsule（manifest、bootstrap 与 PEX runner）。

## 项目发现

所有需要项目上下文的命令（`sf new` / `submit` / `ls` / `validate` …）从当前目录向上查找 `starforge.yaml`，类似 git 找仓库根。

| 方式                                  | 说明                |
| ----------------------------------- | ----------------- |
| `cd my-lab && sf …`                 | 常规：在仓库内或子目录运行     |
| `SF_REPO_ROOT=/path/to/my-lab sf …` | CI / 脚本：显式指定，免 cd |

`sf login` / `logout` / `status` 是全局命令，不要求在项目内。

## 下一步

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
cd my-lab
sf login --server https://<你的 StarForge 域名>
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]
```

| 参数          | 说明                                                                                   |
| ----------- | ------------------------------------------------------------------------------------ |
| `DIRECTORY` | The repo directory (asked interactively when omitted; . means the current directory) |

| 选项            | 说明                                                                      |
| ------------- | ----------------------------------------------------------------------- |
| `--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                                     |