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

# baseten model

> Manage Baseten models

Create, list, and push Baseten models.

Authentication is through `baseten auth login` or the `BASETEN_API_KEY` environment variable.

## push

```sh theme={"system"}
baseten model push [OPTIONS] [--dir DIR]
```

Build a model archive, upload it to Baseten, and create either a new model or a new deployment of an existing model.

The current directory is used by default; pass `--dir` to push a model directory at another path.

The model is identified by the `model_name` field in config.yaml. Use `--override-name` to override that for this push only.

### Options

<ParamField body="--create-environment-if-missing" type="BOOL">
  Create the environment named by --environment when the model does not have it yet. Without this, pushing to an environment that does not exist fails. Only meaningful for an environment other than production, which every model has.
</ParamField>

<ParamField body="--deploy-timeout" type="TEXT">
  Deployment timeout as a duration (e.g. 30m, 1h); allowed range 10m to 24h.
</ParamField>

<ParamField body="--deployment-name" type="TEXT">
  Human-readable name for the new deployment.
</ParamField>

<ParamField body="--develop" type="BOOL">
  Push as a development deployment: the model's single mutable dev slot, created if absent and overwritten in place otherwise. Incompatible with --environment and --deployment-name.
</ParamField>

<ParamField body="--dir" type="TEXT" default=".">
  Model directory to push. Defaults to the current directory.
</ParamField>

<ParamField body="--disable-archive-download" type="BOOL">
  Disable archive download for the new model. Only valid for new models.
</ParamField>

<ParamField body="--dry-run" type="BOOL">
  Validate the push and request upload credentials without uploading or creating anything.
</ParamField>

<ParamField body="--environment" type="TEXT">
  Stable environment to push to. Run 'baseten model environment list' to see a model's environments.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--labels" type="TEXT">
  User-provided labels for the deployment as a JSON object, e.g. '\{"team":"ml","priority":1}'.
</ParamField>

<ParamField body="--no-build-cache" type="BOOL">
  Force a full rebuild without using cached layers.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--override-name" type="TEXT">
  Override the model\_name from config.yaml for this push only. The on-disk config.yaml is not modified.
</ParamField>

<ParamField body="--preserve-env-instance-type" type="BOOL">
  Keep the target environment's current instance type instead of applying the one from config.yaml. Only meaningful when an environment is targeted.
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--region" type="TEXT">
  Slug of the region to deploy the model in. Defaults to a region Baseten selects. Run 'baseten org regions' to see the slugs available.
</ParamField>

<ParamField body="--tail" type="BOOL">
  Stream build and runtime logs to stderr after pushing. Logs are always text-formatted; use 'baseten model deployment logs --tail' for structured log streaming.
</ParamField>

<ParamField body="--team" type="TEXT">
  Team the model belongs to. Only valid for new models.
</ParamField>

<ParamField body="--wait" type="BOOL">
  Block until the deployment is active. Exits non-zero on a terminal-failure status.
</ParamField>

<ParamField body="--watch" type="BOOL">
  After pushing, watch the model directory and live-patch the development deployment on change. Implies --develop.
</ParamField>

<ParamField body="--watch-hot-reload" type="BOOL">
  With --watch, hot-reload the running container when every change is to model code; mixed changes fall back to a cold patch.
</ParamField>

<ParamField body="--watch-no-keepalive" type="BOOL">
  With --watch, let the development deployment scale to zero while watching. By default it is kept warm by periodic pings.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Push the current directory as a new deployment

```sh theme={"system"}
baseten model push
```

Push and stream build/runtime logs until the deployment is active

```sh theme={"system"}
baseten model push --tail --wait
```

### Filter output with `--jq`

Print the new deployment's predict URL

```sh theme={"system"}
baseten model push --jq '.predict_url'
```

### Output

**Text mode (`--output text`):** Narrative summary on stdout: success banner, deployment facts, then grouped next-step hints for viewing logs, invoking the model, and (when the pushed config enables it) SSH access; hints scoped to an environment are tagged "(once deployed)". Under `--output json` the narrative is redirected to stderr so stdout stays a clean JSON document.

**JSON mode (`--output json`):** payload type `cmd.ModelPushResult`.

Under `--dry-run` no upload or deployment happens; the push is validated, upload credentials are requested, and stdout is the empty JSON object `\{\}`. Otherwise stdout is the full model+deployment result.

## watch

```sh theme={"system"}
baseten model watch [OPTIONS] [--dir DIR]
```

Watch a model directory and patch the model's development deployment in place on every change, skipping a full rebuild.

The current directory is used by default; pass `--dir` to watch a model directory at another path. The model is identified by the `model_name` field in that directory's config.yaml, like `baseten model push`.

The model must already have a development deployment; if it does not, run `baseten model push --develop` (or `baseten model push --watch`) first.

Runs until interrupted. Some changes cannot be expressed as a patch (removing config.yaml, or any change under the data directory); the watcher reports these and you must re-push.

### Options

<ParamField body="--dir" type="TEXT" default=".">
  Model directory to watch. Defaults to the current directory.
</ParamField>

<ParamField body="--hot-reload" type="BOOL">
  Hot-reload the running container when every change is to model code; mixed changes fall back to a cold patch.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--no-keepalive" type="BOOL">
  Let the development deployment scale to zero while watching. By default it is kept warm by periodic pings.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--team" type="TEXT">
  Team the model belongs to. Use to disambiguate when the same model\_name exists in multiple teams.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Watch the current directory against its model's development deployment

```sh theme={"system"}
baseten model watch
```

Watch another directory and hot-reload on model-code changes

```sh theme={"system"}
baseten model watch --dir ./my-model --hot-reload
```

### Output

**Text mode (`--output text`):** Streams patch and sync status to stderr as changes are applied. Runs until interrupted and produces no stdout output.

**JSON mode (`--output json`):** payload type `cmd.JSONUndefined`.

## list

```sh theme={"system"}
baseten model list [OPTIONS]
```

List Baseten models.

### Options

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--team" type="TEXT">
  Team name or ID to scope the listing to. Defaults to all teams the caller can see.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

List all models accessible to the caller

```sh theme={"system"}
baseten model list
```

List only models in a specific team

```sh theme={"system"}
baseten model list --team my-team
```

### Filter output with `--jq`

Print just the model IDs

```sh theme={"system"}
baseten model list --jq '.models[].id'
```

### Output

**Text mode (`--output text`):** Table with columns: ID, NAME, TEAM, DEPLOYMENTS, CREATED. When no models exist, prints "No models found." to stderr.

**JSON mode (`--output json`):** payload type `managementapi.Models`.

## describe

```sh theme={"system"}
baseten model describe [OPTIONS]
```

Describe a Baseten model.

### Options

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--model-id" type="TEXT">
  ID of the model.

  Mutually exclusive with other flags in group `model-ref`.
</ParamField>

<ParamField body="--model-name" type="TEXT">
  Name of the model. Use --team to disambiguate when the same name exists in multiple teams.

  Mutually exclusive with other flags in group `model-ref`.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--team" type="TEXT">
  Team name or ID. Only valid with --model-name.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Describe a model by ID

```sh theme={"system"}
baseten model describe --model-id <model-id>
```

Describe a model by name

```sh theme={"system"}
baseten model describe --model-name <name>
```

### Filter output with `--jq`

Print the production deployment ID

```sh theme={"system"}
baseten model describe --model-id <model-id> --jq '.production_deployment_id'
```

### Output

**Text mode (`--output text`):** Field-per-line summary: ID, Name, Team, Deployments, Instance, Production, Development, Created. Optional fields are omitted when unset.

**JSON mode (`--output json`):** payload type `managementapi.Model`.

## predict

```sh theme={"system"}
baseten model predict [OPTIONS]
```

POST a JSON request to a model and write the response to stdout.

Targets the production environment by default. Use `--environment`, `--deployment-id`, `--deployment-name`, or `--regional` to target something else.

Streaming responses (Transfer-Encoding: chunked) are passed through as they arrive. For machine-readable streaming JSON from OpenAI-compatible models, use `--output jsonl`.

### Options

<ParamField body="--data" type="TEXT">
  Inline JSON request body. The shape is the deployed model's own input schema; see [https://docs.baseten.co/inference/calling-your-model](https://docs.baseten.co/inference/calling-your-model).

  Mutually exclusive with other flags in group `predict-input`.
</ParamField>

<ParamField body="--deployment-id" type="TEXT">
  Specific deployment to target. Mutually exclusive with --environment, --deployment-name, and --regional.
</ParamField>

<ParamField body="--deployment-name" type="TEXT">
  Name of the deployment to target. Mutually exclusive with --environment, --deployment-id, and --regional.
</ParamField>

<ParamField body="--environment" type="TEXT">
  Environment to target (e.g. production, development). Defaults to production. Mutually exclusive with --deployment-id, --deployment-name, and --regional. Run 'baseten model environment list' to see a model's environments.
</ParamField>

<ParamField body="--file" type="TEXT">
  Path to a JSON file containing the request body. Use '-' for stdin.

  Mutually exclusive with other flags in group `predict-input`.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--model-id" type="TEXT">
  ID of the model.

  Mutually exclusive with other flags in group `model-ref`.
</ParamField>

<ParamField body="--model-name" type="TEXT">
  Name of the model. Use --team to disambiguate when the same name exists in multiple teams.

  Mutually exclusive with other flags in group `model-ref`.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--regional" type="TEXT">
  Regional environment name; routes through the regional hostname. Mutually exclusive with --environment, --deployment-id, and --deployment-name.
</ParamField>

<ParamField body="--team" type="TEXT">
  Team name or ID. Only valid with --model-name.
</ParamField>

<ParamField body="--websocket" type="BOOL">
  Use the WebSocket predict endpoint. Sends the body as one frame, reads one frame back, then closes. Not for multi-message or back-and-forth sessions.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Send an inline JSON body

```sh theme={"system"}
baseten model predict --model-id <model-id> --data '{"prompt":"hello"}'
```

Send a request body from a file

```sh theme={"system"}
baseten model predict --model-id <model-id> --file request.json
```

### Filter output with `--jq`

Extract a field when the model returns JSON

```sh theme={"system"}
baseten model predict --model-id <model-id> --data '{"x":1}' --jq '.result'
```

### Output

**Text mode (`--output text`):** The model's response body, passed through verbatim. May be JSON, plain text, or binary, and may stream when the model uses chunked transfer encoding or SSE.

**JSON mode (`--output json`):** payload type `cmd.JSONUndefined`.

Under `--output json`, binary frames are base64-encoded under a 'body' key. Under `--output jsonl`, each SSE or binary chunk is emitted as its own record, one per line.

## delete

```sh theme={"system"}
baseten model delete [OPTIONS]
```

Delete a Baseten model and all of its deployments.

Prompts for the model name to confirm the deletion. Pass `--yes` to skip the prompt. When stdin is not a terminal, `--yes` is required.

### Options

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--model-id" type="TEXT">
  ID of the model.

  Mutually exclusive with other flags in group `model-ref`.
</ParamField>

<ParamField body="--model-name" type="TEXT">
  Name of the model. Use --team to disambiguate when the same name exists in multiple teams.

  Mutually exclusive with other flags in group `model-ref`.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--team" type="TEXT">
  Team name or ID. Only valid with --model-name.
</ParamField>

<ParamField body="--yes" type="BOOL">
  Skip the interactive confirmation prompt. Required when stdin is not a terminal.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Delete by ID without confirmation

```sh theme={"system"}
baseten model delete --model-id <model-id> --yes
```

Delete by name with interactive confirmation

```sh theme={"system"}
baseten model delete --model-name <name>
```

### Filter output with `--jq`

Print the deleted model's ID

```sh theme={"system"}
baseten model delete --model-id <model-id> --yes --jq '.id'
```

### Output

**Text mode (`--output text`):** On success, prints "Deleted model `name` (`id`)" to stderr; no stdout output.

**JSON mode (`--output json`):** payload type `managementapi.ModelTombstone`.

## rename

```sh theme={"system"}
baseten model rename [OPTIONS]
```

Change a model's name. The new name must be unique within the model's team.

Renaming does not change the model ID, endpoints, or deployments. Pushes that still use the old `model_name` create another model or target a model that now uses that name, so update `config.yaml` after renaming.

Run `baseten model describe` to see the current values.

### Options

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--model-id" type="TEXT">
  ID of the model.

  Mutually exclusive with other flags in group `model-ref`.
</ParamField>

<ParamField body="--model-name" type="TEXT">
  Name of the model. Use --team to disambiguate when the same name exists in multiple teams.

  Mutually exclusive with other flags in group `model-ref`.
</ParamField>

<ParamField body="--new-name" type="TEXT" required>
  New name for the model, unique within its team.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--team" type="TEXT">
  Team name or ID. Only valid with --model-name.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Rename by ID

```sh theme={"system"}
baseten model rename --model-id <model-id> --new-name my-model-v2
```

Rename by name, scoped to a team

```sh theme={"system"}
baseten model rename --model-name <name> --team <team> --new-name my-model-v2
```

### Filter output with `--jq`

Print the model's new name

```sh theme={"system"}
baseten model rename --model-id <model-id> --new-name my-model-v2 --jq '.name'
```

### Output

**Text mode (`--output text`):** On success, prints "Renamed model `id` to `name`" and a reminder to update `model_name` in `config.yaml` to stderr (also under `--output json`); no stdout output.

**JSON mode (`--output json`):** payload type `managementapi.Model`.

## audit-logs

```sh theme={"system"}
baseten model audit-logs [OPTIONS]
```

List audit-log entries scoped to a single model, newest first.

Returns up to `--limit` entries (default 20) across the full history by default. Use `--start`/`--end` or `--since` to scope the time window, and the filter flags (`--event-type-group`, `--source`, `--user-id`, `--deployment-id`, `--environment`, `--search`) to narrow results within the model.

For machine-readable streaming, prefer `--output jsonl` over `--output json`.

### Options

<ParamField body="--deployment-id" type="TEXT (repeatable)">
  Only return entries referencing one of these model deployment IDs. May be repeated.
</ParamField>

<ParamField body="--direction" type="TEXT" default="desc">
  Sort order by the time the action occurred: 'desc' (newest first) or 'asc' (oldest first).

  One of: `asc`, `desc`
</ParamField>

<ParamField body="--end" type="TEXT">
  End of the time window. Accepts ISO 8601; values without a timezone designator are interpreted in the local timezone. Defaults to now.
</ParamField>

<ParamField body="--environment" type="TEXT (repeatable)">
  Only return entries for one of these environments. May be repeated.
</ParamField>

<ParamField body="--event-type-group" type="TEXT (repeatable)">
  Only return entries whose event type falls in one of these groups. May be repeated. One of: activated-deactivated, api-keys, autoscaling-settings, deleted, deployed, directory-group-management, environment-settings, gateway, instance-type-changed, promoted, replica-terminated, secrets, ssh, user-management, webhook-signing-secrets.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--limit" type="INTEGER" default="20">
  Maximum number of entries to return, paging as needed. Use 0 for no limit (every entry in the window).
</ParamField>

<ParamField body="--model-id" type="TEXT">
  ID of the model.

  Mutually exclusive with other flags in group `model-ref`.
</ParamField>

<ParamField body="--model-name" type="TEXT">
  Name of the model. Use --team to disambiguate when the same name exists in multiple teams.

  Mutually exclusive with other flags in group `model-ref`.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--search" type="TEXT">
  Case-insensitive substring matched against resource names and IDs in the entry.
</ParamField>

<ParamField body="--since" type="TEXT">
  Shortcut for a window from a relative time ago until now. Accepts a duration (e.g. '30m', '1h30m') or '`N`d' (e.g. '3d'). Mutually exclusive with --start and --end.
</ParamField>

<ParamField body="--source" type="TEXT (repeatable)">
  Only return entries issued from one of these surfaces. May be repeated. One of: ui, api, mcp, other.
</ParamField>

<ParamField body="--start" type="TEXT">
  Start of the time window. Accepts ISO 8601 (e.g. '2026-05-14', '2026-05-14T12:00:00', '2026-05-14T12:00:00Z'). Values without a timezone designator are interpreted in the local timezone. Defaults to the beginning of the audit-log history.
</ParamField>

<ParamField body="--team" type="TEXT">
  Team name or ID. Only valid with --model-name.
</ParamField>

<ParamField body="--user-id" type="TEXT (repeatable)">
  Only return entries whose acting user is one of these IDs. May be repeated.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

List the 20 most recent audit-log entries for a model

```sh theme={"system"}
baseten model audit-logs --model-id <model-id>
```

List promote events for a model over the last 30 days

```sh theme={"system"}
baseten model audit-logs --model-name <name> --since 30d --event-type-group promoted
```

### Filter output with `--jq`

Stream each entry's event type as a JSONL stream

```sh theme={"system"}
baseten model audit-logs --model-id <model-id> --output jsonl --jq '.event_type'
```

### Output

**Text mode (`--output text`):** Table with columns: TIME, ACTOR, EVENT, SOURCE. When no entries match, prints "No audit-log entries found." to stderr.

**JSON mode (`--output json`):** payload type `managementapi.AuditLogEntry`.