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

# CLI commands

> The CLI is for agents, but here for your reference.

Usually you just ask your agent, and it runs these commands for you. You can also run any of them yourself. `auremi --help` (or `auremi <command> --help`) lists every command with its flags. If you're new, start with [Getting started](/getting-started).

Any command that queues work takes `--no-run`, which shows what would run without starting it.

## Setup and account

* `auremi login`: signs you in through your browser. Run this one yourself. Your agent will ask you to when its session expires.
* `auremi whoami`: shows who you are signed in as, and on which Auremi server.
* `auremi --version`: prints the installed CLI version.
* `auremi docs`: downloads the Auremi guides your agent reads into `.auremi/docs`.
* `auremi docs check`: confirms those guides match your Auremi server.
* `auremi backend add <name> <url>`: saves an Auremi server under a name, for example a staging server alongside auremi.ai.
* `auremi backend use <name>`: switches the CLI to a saved server.
* `auremi backend list`: lists your saved servers.
* `auremi backend show`: shows the server the CLI is using now.
* `auremi backend remove <name>`: forgets a saved server.

## Your model repo and notebook

* `auremi init --name <name>`: sets up a new model repo from the Auremi template, including the agent skill.
* `auremi open --project <projectId>`: prints the web link for a project. Leave out the project to get the link for creating a new model.
* `auremi source push`: uploads your uncommitted work as a snapshot you can train from, with no Git commit needed.
* `auremi source refresh`: asks Auremi to pick up your pushed GitHub branch again if it hasn't appeared.
* `auremi notebook push`: publishes your notebook and model code as a new notebook revision.
* `auremi notebook status`: shows the latest published notebook revision.
* `auremi notebook open`: prints the link to your model's notebook.

```bash theme={null}
auremi notebook push --message "Add a loss chart"
```

## Checking your work

* `auremi check`: builds your model and checks that the model, training, inference and validation code is valid.
* `auremi validate check`: confirms your validators and validation data are ready, without running them.
* `auremi verify`: trains on one example for one epoch, then runs inference on it, as a quick local test.
* `auremi validate pull`: downloads the validation data and validators you need to validate on your own machine.
* `auremi validate --run <runDir>`: validates a trained model on your own machine.

<Note>
  PyTorch model repos can't use several commands yet, including `auremi check`, `auremi validate`, `auremi notebook push`, `auremi source push` and `auremi deploy`.
</Note>

## Training and runs

* `auremi train`: starts a training run. Add `--target` to choose where it runs: `browser`, `local`, `vertex` or `sagemaker`.
* `auremi hypothesis run <file.md>`: tests an experiment you've written down. It trains, validates and tests your current uncommitted code, then compares the result with a baseline.
* `auremi run status <runId>`: shows a run's current stage, epoch, loss and time remaining. Add `--watch` to keep it updating.
* `auremi compare <runId>`: shows how a run scored against your primary branch.
* `auremi validate --queue --run <runId>`: runs validation on a finished run.
* `auremi test --run <runId>`: evaluates a finished run on your test dataset.
* `auremi branches show`: shows your primary branch, tracked branches and each branch's hypothesis.
* `auremi branches set-primary <branch>`: sets the branch that experiments are compared against.
* `auremi branches set-hypothesis <branch> --text "<hypothesis>"`: records what a branch is meant to improve.
* `auremi jobs status <jobId> --project <projectId>`: shows where a job is up to.
* `auremi jobs wait <jobId> --project <projectId>`: waits for a job to finish.
* `auremi jobs cancel <jobId> --project <projectId>`: cancels a job.
* `auremi jobs restart <jobId> --project <projectId>`: restarts a failed, paused or cancelled browser job from its last checkpoint.

```bash theme={null}
auremi train --no-run
auremi train --pipeline --scorecard --wait --hypothesis "Lower loss on long clips"
```

The second example trains, validates and tests in one go, then scores the run against your primary branch.

To train or test using only files on your machine, without contacting Auremi, add `--local-only --data <dir>` to `auremi train` or `auremi test`.

## Models and inference

* `auremi model list`: lists the trained models for this repo. Sort them with `--best`, `--newest` or `--test-loss`.
* `auremi model pull <sha|runId>`: downloads a trained model into `.auremi/models`. Use `--best` instead of an ID to download the top-ranked one.
* `auremi infer --run .auremi/models/<sha> --input <file>`: runs a downloaded model on one input on your machine. Add `--out <file>` to save the result.
* `auremi deploy --run <runId> --target cloud-run|sagemaker-serverless`: deploys a trained model as a serverless endpoint on Google Cloud Run or SageMaker Serverless, in your own cloud account.

```bash theme={null}
auremi model pull --best
auremi infer --run .auremi/models/<sha> --input photo.png --out result.png
```

## Datasets

* `auremi dataset scan <dir>`: writes a manifest of the examples in a local dataset folder.
* `auremi dataset push <dir> --project <projectId>`: uploads a local dataset to Auremi. If an upload is interrupted, it resumes where it stopped.
* `auremi dataset list`: lists your datasets and their versions.
* `auremi dataset link <datasetSourceId> --project <projectId>`: makes an existing dataset available to a project.
* `auremi dataset derive --from <datasetVersionId> --terms <a,b>`: previews a smaller dataset of only the examples whose transcripts contain those words. Add `--apply` to create it.
* `auremi dataset pull --split train|test`: downloads a dataset split to your machine for local runs.
* `auremi dataset cache status`: shows how much disk space downloaded datasets are using.
* `auremi dataset cache prune`: trims downloaded datasets back to the cache size limit. Add `--all` to clear them all.
* `auremi dataset delete <datasetId> --yes`: deletes a dataset and every version of it.

## Moving models between servers

* `auremi promote <runId> --to <backend>`: copies a trained model from one Auremi server to another. Add `--dry-run` to preview.
* `auremi promote status`: lists the models that have an open public share on a server.
* `auremi promote publish <runId>`: opens a model for transfer and prints its share link.
* `auremi promote import <shareUrl> --to <backend>`: pulls a model from a share link into another server.
* `auremi promote lock <shareSlug>`: closes an open share again. Use `--all` to close every open share.

You normally only need `auremi promote`. The other four commands are for finishing or cleaning up a transfer that stopped partway.

## Cloud compute

* `auremi cloud-compute list`: shows the cloud training providers you've set up.
* `auremi cloud-compute configure vertex|sagemaker`: sets up Vertex AI or SageMaker for training, including machine type and spending limits.
* `auremi cloud-compute push-runner vertex|sagemaker`: builds the Auremi training container and uploads it to your cloud account.
* `auremi cloud-compute test vertex|sagemaker`: checks whether a provider is ready to use.
* `auremi cloud-compute smoke-test vertex|sagemaker --dataset <datasetVersionId>`: checks that a training container can start on the provider, then cancels it. No training happens.
* `auremi cloud-compute remove vertex|sagemaker`: removes a provider setup.