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

> Manage the model registry

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf model register alice/support-agent --run run-4f2a91 --version 3
sf model ls
sf model promote alice/support-agent@3
```

The model registry: a named version line that outlives the run that produced it.

A run id is a fact about an experiment. A model version is a decision — this is the one we are
willing to serve. Registering turns the first into the second, and everything downstream
(deployments, the Playground, acceptance cards) refers to the version rather than the run.

| Command             | When you reach for it                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------- |
| `sf model register` | A run produced something worth keeping                                                   |
| `sf model promote`  | That version is the one production should use                                            |
| `sf model card`     | Show or export the acceptance card — what it shipped on, frozen at the moment it shipped |
| `sf model archive`  | Take a version out of circulation without deleting its history                           |
| `sf model ls`       | What exists, and which version is promoted                                               |

See [Model registry](/en/guides/model-registry) for the workflow.

## `sf model`

Manage the model registry

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf model <subcommand>
```

| Command             | Description                          |
| ------------------- | ------------------------------------ |
| `sf model archive`  | Archive one version                  |
| `sf model card`     | Show or export the acceptance card   |
| `sf model ls`       | List models and their versions       |
| `sf model promote`  | Promote one version to production    |
| `sf model register` | Record a run's artifact as a version |

### `sf model archive`

Archive one version

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf model archive <MODEL> <VERSION>
```

| Argument  | Description                                |
| --------- | ------------------------------------------ |
| `MODEL`   | Model id (\<owner>/\<name>) (**required**) |
| `VERSION` | Version number (**required**)              |

No options beyond `--help`.

### `sf model card`

Show or export the acceptance card

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf model card <MODEL> <VERSION> [options]
```

| Argument  | Description                                |
| --------- | ------------------------------------------ |
| `MODEL`   | Model id (\<owner>/\<name>) (**required**) |
| `VERSION` | Version number (**required**)              |

| Option     | Description                             |
| ---------- | --------------------------------------- |
| `--export` | Write the card as Markdown to this path |

### `sf model ls`

List models and their versions

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf model ls [MODEL]
```

| Argument | Description                                        |
| -------- | -------------------------------------------------- |
| `MODEL`  | Model id (\<owner>/\<name>); omit to list them all |

No options beyond `--help`.

### `sf model promote`

Promote one version to production

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf model promote <MODEL> <VERSION>
```

| Argument  | Description                                |
| --------- | ------------------------------------------ |
| `MODEL`   | Model id (\<owner>/\<name>) (**required**) |
| `VERSION` | Version number (**required**)              |

No options beyond `--help`.

### `sf model register`

Record a run's artifact as a version

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf model register <MODEL> [options]
```

| Argument | Description                                                                        |
| -------- | ---------------------------------------------------------------------------------- |
| `MODEL`  | Model name (lands in your own namespace) or a full \<owner>/\<name> (**required**) |

| Option          | Description                                                     |
| --------------- | --------------------------------------------------------------- |
| `--run`, `-r`   | Register from this run's hf\_export artifact                    |
| `--path`        | Record a weights path directly (a base model, external weights) |
| `--notes`, `-n` | What changed in this version                                    |
| `--desc`        | Model description (write it on the first registration)          |