baseten auth login or the BASETEN_API_KEY environment variable.
push
--dir to push a model directory at another path. If your model only needs a configuration file, pass --file to push that file directly without creating a model directory. The CLI uploads the file as config.yaml. You can’t combine --file and --dir.
Baseten identifies the model by the model_name field in config.yaml. Use --override-name to change the name for this push without editing the file.
A push can set the new deployment’s instance type (--instance-type), autoscaling (--min-replica, --max-replica, and the other autoscaling flags), and request backpressure (--request-backpressure-policy) without editing config.yaml. With --environment, the environment keeps those settings after the promotion. The promotion-only flags --autoscaling-schedule-update-json and --override-* apply only with --environment. --instance-type can’t be combined with --preserve-env-instance-type.
Options
Autoscaling schedule changes for the environment, applied when the promotion completes, as a JSON object with schedules, delete_schedules, and timezone. Same shape and values as autoscaling_schedule_settings on the environment update API, for example cadence DAILY. Requires
--environment.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.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.Stable environment to push to. Run ‘baseten model environment list’ to see a model’s environments.
Config file to push on its own, for models defined entirely by their config. Use - for stdin. Only this file is uploaded, as the model’s config.yaml. Mutually exclusive with
--dir.Attach the git commit, latest tag, commits since that tag, and whether there are uncommitted changes, when the model directory is in a git repository.
Instance type for the new deployment, for example A10Gx4x16, instead of the one in config.yaml. With
--environment, the environment keeps it once the promotion completes. See https://docs.baseten.co/deployment/resources for the available types. Cannot be combined with --preserve-env-instance-type.Maximum percentage of replicas that can be removed per autoscaling window (1-50). For example, 20 means at most 20% of replicas are removed per window.
For this promotion only, the maximum unavailable percentage for rolling deploys.
Override the model_name from config.yaml for this push only. The on-disk config.yaml is not modified.
For this promotion only, the cleanup strategy to use after it completes.One of:
keep, scale-to-zero, deactivateKeep the target environment’s current instance type instead of applying the one from config.yaml. Only meaningful when an environment is targeted.
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Slug of the region to deploy the model in. Defaults to a region Baseten selects. Run ‘baseten org regions’ to see the slugs available.
Backpressure policy for the new deployment. With
--environment, the environment keeps it once the promotion completes. Pass null to clear the policy.One of: queue-on-full, reject-on-full, nullStream build and runtime logs to stderr after pushing. Logs are always text-formatted; use ‘baseten model deployment logs
--tail’ for structured log streaming.After pushing, watch the model directory and live-patch the development deployment on change. Implies
--develop.With
--watch, hot-reload the running container when every change is to model code; mixed changes fall back to a cold patch.With
--watch, let the development deployment scale to zero while watching. By default it is kept warm by periodic pings.Examples
Push the current directory as a new deploymentFilter output with --jq
Print the new deployment’s 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. With --wait, if the deployment doesn’t become active and Baseten reports why, the command prints the status and reason and exits with an error that includes them.
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
--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
Hot-reload the running container when every change is to model code; mixed changes fall back to a cold patch.
Let the development deployment scale to zero while watching. By default it is kept warm by periodic pings.
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Team the model belongs to. Use to disambiguate when the same model_name exists in multiple teams.
Examples
Watch the current directory against its model’s development deploymentOutput
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
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
List all models accessible to the callerFilter output with --jq
Print just the model IDs
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
Options
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Describe a model by IDFilter output with --jq
Print the 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
--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.
Pass --verbose to log the request URL, the response status, and the response headers to stderr.
Options
Inline JSON request body. The shape is the deployed model’s own input schema; see https://docs.baseten.co/inference/calling-your-model.Mutually exclusive with other flags in group
predict-input.Specific deployment to target. Mutually exclusive with
--environment, --deployment-name, and --regional.Name of the deployment to target. Mutually exclusive with
--environment, --deployment-id, and --regional.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.Path to a JSON file containing the request body. Use ’-’ for stdin.Mutually exclusive with other flags in group
predict-input.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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Regional environment name; routes through the regional hostname. Mutually exclusive with —environment, —deployment-id, and —deployment-name.
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.
Examples
Send an inline JSON bodyFilter output with --jq
Extract a field when the model returns JSON
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
--yes to skip the prompt. When stdin is not a terminal, --yes is required.
Options
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Delete by ID without confirmationFilter output with --jq
Print the deleted model’s 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
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
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Rename by IDFilter output with --jq
Print the model’s new 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
--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
Only return entries referencing one of these model deployment IDs. May be repeated.
Sort order by the time the action occurred: ‘desc’ (newest first) or ‘asc’ (oldest first).One of:
asc, descEnd of the time window. Accepts ISO 8601; values without a timezone designator are interpreted in the local timezone. Defaults to now.
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.
Maximum number of entries to return, paging as needed. Use 0 for no limit (every entry in the window).
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Shortcut for a window from a relative time ago until now. Accepts a duration (e.g. ‘30m’, ‘1h30m’) or ‘
Nd’ (e.g. ‘3d’). Mutually exclusive with --start and --end.Only return entries issued from one of these surfaces. May be repeated. One of: ui, api, mcp, other.
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.
Examples
List the 20 most recent audit-log entries for a modelFilter output with --jq
Stream each entry’s event type as a JSONL stream
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.
deployment
Deployments are the instances of a model that serve traffic. Activate and deactivate them, read their config, logs, and metrics, and change their autoscaling and request backpressure settings.activate
Options
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Activate a deploymentFilter output with --jq
Print just the success flag
Output
Text mode (--output text): On success, prints “Activated deployment id” to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.ActivateResponse.
config
--output json to emit the full response {config, raw_config} as JSON.
Options
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Print the deployment’s config.yamlFilter output with --jq
Extract the parsed model_name field
Output
Text mode (--output text): The original config.yaml text (preserving comments and ordering) when available, otherwise the parsed config marshaled as YAML.
JSON mode (--output json): payload type managementapi.DeploymentConfigResponse.
The full {config, raw_config} envelope. raw_config is the original config.yaml text; config is the parsed shape.
deactivate
--yes to skip the prompt. When stdin is not a terminal, --yes is required.
Options
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Deactivate a deployment without the confirmation promptFilter output with --jq
Print just the success flag
Output
Text mode (--output text): On success, prints “Deactivated deployment id” to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.DeactivateResponse.
download
--out-file or --out-dir is required. --out-file writes the raw tar bytes; --out-dir extracts the tar into the directory. Use --overwrite to replace an existing file or write into a non-empty directory.
Options
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.Extract the model source tar into this directory.Mutually exclusive with other flags in group
download-out.Save the model source as an uncompressed tar file at this path.Mutually exclusive with other flags in group
download-out.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Save the model source as a tar fileFilter output with --jq
Print just the destination path
Output
Text mode (--output text): Writes the model source to disk; prints progress and the final destination path to stderr; no stdout output.
JSON mode (--output json): payload type cmd.ModelDeploymentDownloadResult.
On success, stdout is a JSON object with either out_file or out_dir set to the path written.
promote
model environment update-promotion before promoting the deployment.
A promotion can also change the target environment’s settings: --region, --instance-type, --request-backpressure-policy, the autoscaling flags, and --autoscaling-schedule-update-json for autoscaling schedules as raw API JSON. The --override-* flags change the promotion’s settings for this promotion only. The confirmation prompt names the settings the promotion changes.
Prompts for yes/no confirmation. Pass --yes to skip the prompt. When stdin is not a terminal, --yes is required.
Options
Autoscaling schedule changes for the environment, applied when the promotion completes, as a JSON object with schedules, delete_schedules, and timezone. Same shape and values as autoscaling_schedule_settings on the environment update API, for example cadence DAILY.
Instance type to set on the environment, for example A10Gx4x16. See https://docs.baseten.co/deployment/resources for the available types. Cannot be combined with
--preserve-env-instance-type.Maximum percentage of replicas that can be removed per autoscaling window (1-50). For example, 20 means at most 20% of replicas are removed per window.
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.For this promotion only, the maximum unavailable percentage for rolling deploys.
For this promotion only, the cleanup strategy to use after it completes.One of:
keep, scale-to-zero, deactivateKeep the target environment’s current instance type instead of applying the promoted deployment’s.
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Region slug to set on the environment. Pass an empty string for Global. Run ‘baseten org regions’ to see the slugs available.
Backpressure policy to set on the environment. Pass null to clear the environment’s policy.One of:
queue-on-full, reject-on-full, nullExamples
Promote a deployment to production without the confirmation promptFilter output with --jq
Print the promoted deployment’s status
Output
Text mode (--output text): On success, prints “Promoted deployment id to environment env” to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.Deployment.
Under --output json, the promoted deployment object.
delete
--yes to skip the prompt. When stdin is not a terminal, --yes is required.
Options
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Delete a deployment without the confirmation promptFilter output with --jq
Print the deleted deployment’s ID
Output
Text mode (--output text): On success, prints “Deleted deployment id” to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.DeploymentTombstone.
describe
Options
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Describe a deployment by IDFilter output with --jq
Print just the deployment status
Output
Text mode (--output text): Field-per-line summary: ID, Name, Model, Environment (optional), Status, Failure (when Baseten reports why the deployment failed), Instance (optional), Replicas, Created.
JSON mode (--output json): payload type managementapi.Deployment.
list
Options
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
List all deployments of a modelFilter output with --jq
Print just the deployment IDs
Output
Text mode (--output text): Table with columns: ID, NAME, ENVIRONMENT, STATUS, INSTANCE, REPLICAS, CREATED. When no deployments exist, prints “No deployments found.” to stderr.
JSON mode (--output json): payload type managementapi.Deployments.
logs
--limit lines from the last 30 minutes, newest first, and prints a note to stderr when --limit trims older lines. Use --start/--end or --since to scope the window (max 7 days). Use --tail to stream live logs until the deployment leaves a runnable state or you interrupt with Ctrl-C.
For machine-readable streaming, prefer --output jsonl over --output json.
For request-ID tracing, scope, and log export, see Logs.
Options
End of the log time range. Accepts ISO 8601; values without a timezone designator are interpreted in the local timezone. Default is now. Window must be at most 7 days.
Case-sensitive substring that must appear in the log message. May be repeated; all must match.
Maximum number of log lines to return, paging backward from the end of the window. Use 0 for no limit (every log line in the window). Not applicable with
--tail.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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
RE2 regular expression matched against the log message. Prefer
--includes and --excludes for plain substring matches.Shortcut for fetching logs from a relative time ago until now. Accepts a duration (e.g. ‘30m’, ‘1h30m’) or ‘
Nd’ (e.g. ‘3d’). Maximum ‘7d’. Mutually exclusive with --start and --end.Start of the log time range. 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. Default is 30 minutes before the end. Window must be at most 7 days.
Stream new logs as they arrive until the deployment leaves a runnable state or you interrupt with Ctrl-C. Cannot be combined with the time-range or filter flags. For machine-readable streaming, prefer
--output jsonl over --output json.Examples
Print logs for a deployment over the last hourFilter output with --jq
Stream just the log messages as a JSONL stream
Output
Text mode (--output text): One line per log record: “[YYYY-MM-DD HH:MM:SS]: (replica) message”.
JSON mode (--output json): payload type managementapi.Log.
metrics
--mode current for a snapshot, --mode summary to aggregate a window, or --mode series to plot values over time. Scope the window with --since or --start/--end (max 7 days; only applies to summary and series), and select metrics with one or more --metric flags.
Options
End of the metrics time range. Accepts ISO 8601; values without a timezone designator are interpreted in the local timezone. If omitted, the server defaults the end to now. Window must be at most 7 days.
Name of a metric to return; see https://docs.baseten.co/observability/export-metrics/supported-metrics for the available names. May be repeated. When omitted, a default set is returned.
Aggregation mode. ‘current’ returns an instantaneous snapshot at now; ‘summary’ aggregates the whole window into one value per metric; ‘series’ returns evenly-spaced points across the window.
--start/--end/--since are only meaningful for summary and series.One of: current, summary, seriesName of the model. Use
--team to disambiguate when the same name exists in multiple teams.Mutually exclusive with other flags in group model-ref.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Shortcut for a window from a relative time ago until now. Accepts a duration (e.g. ‘30m’, ‘1h30m’) or ‘
Nd’ (e.g. ‘3d’). Maximum ‘7d’. Mutually exclusive with --start and --end.Start of the metrics time range. 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. If omitted, the server defaults the start to one hour before the end. Window must be at most 7 days.
Examples
Show a current snapshot of the default metricsFilter output with --jq
Print the metric names returned
Output
Text mode (--output text): For current and summary, a table with columns METRIC, one column per label dimension (for example QUANTILE, STAT), and VALUE; summary counter values show “total (rate/s)”. For series, a sparkline per metric label set with its min-max range and end value, or a per-step table under --no-chart.
JSON mode (--output json): payload type managementapi.GetModelMetricsResponse.
The metrics response: metric_descriptors, index-mapped metric_values, the resolved mode, and the returned window.
rename
baseten model deployment describe to see the current values.
Options
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.New name for the deployment, unique among the model’s deployments. Only alphanumeric characters, hyphens, underscores, and periods are allowed.
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Rename a deploymentFilter output with --jq
Print the deployment’s new name
Output
Text mode (--output text): On success, prints “Renamed deployment id to name” to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.Deployment.
update-autoscaling
baseten model deployment describe to see the current values.
Options
Maximum percentage of replicas that can be removed per autoscaling window (1-50). For example, 20 means at most 20% of replicas are removed per window.
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Raise a deployment’s replica boundsFilter output with --jq
Print just the status
Output
Text mode (--output text): The status of the request followed by the server’s message.
JSON mode (--output json): payload type managementapi.UpdateAutoscalingSettingsResponse.
update-request-backpressure
--policy null to clear an existing policy and fall back to the default.
Run baseten model deployment describe to see the current values.
Options
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.Backpressure policy to apply. Pass null to clear an existing policy.One of:
queue-on-full, reject-on-full, nullUse a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Reject requests once the queue is fullFilter output with --jq
Print the resulting policy
Output
Text mode (--output text): The resulting policy, or “none” when no policy is set.
JSON mode (--output json): payload type managementapi.RequestBackpressureSettings.
deployment replica
Inspect and terminate individual replicas of a deployment.terminate
--yes to skip the prompt. When stdin is not a terminal, --yes is required.
Options
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Terminate a replica without the confirmation promptFilter output with --jq
Print just the success flag
Output
Text mode (--output text): On success, prints “Terminated replica id of deployment id” to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.TerminateReplicaResponse.
environment
An environment such as production or development points at the deployment currently serving it. Activate it, read its logs and metrics, and configure promotion, autoscaling, and request backpressure.activate
Options
Name of the environment (e.g. production). Run ‘baseten model environment list’ to see a model’s environments.
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Activate the deployment associated with an environmentFilter output with --jq
Print just the success flag
Output
Text mode (--output text): On success, prints “Activated environment name” to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.ActivateResponse.
deactivate
--yes to skip the prompt. When stdin is not a terminal, --yes is required.
Options
Name of the environment (e.g. production). Run ‘baseten model environment list’ to see a model’s environments.
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Deactivate an environment without the confirmation promptFilter output with --jq
Print just the success flag
Output
Text mode (--output text): On success, prints “Deactivated environment name” to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.DeactivateResponse.
describe
Options
Name of the environment (e.g. production). Run ‘baseten model environment list’ to see a model’s environments.
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Describe the production environment of a modelFilter output with --jq
Print the current deployment ID
Output
Text mode (--output text): Field-per-line summary: Name, Model, Current Deployment, Status, Candidate Deployment (optional), Created.
JSON mode (--output json): payload type managementapi.Environment.
list
Options
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
List all environments of a modelFilter output with --jq
Print just the environment names
Output
Text mode (--output text): Table with columns: NAME, CURRENT DEPLOYMENT, STATUS. When no environments exist, prints “No environments found.” to stderr.
JSON mode (--output json): payload type managementapi.Environments.
logs
--limit lines from the last 30 minutes, newest first, and prints a note to stderr when --limit trims older lines. Use --start/--end or --since to scope the window (max 7 days). Use --tail to stream live logs until the environment’s current deployment leaves a runnable state or you interrupt with Ctrl-C.
For machine-readable streaming, prefer --output jsonl over --output json.
For request-ID tracing, scope, and log export, see Logs.
Options
End of the log time range. Accepts ISO 8601; values without a timezone designator are interpreted in the local timezone. Default is now. Window must be at most 7 days.
Name of the environment (e.g. production). Run ‘baseten model environment list’ to see a model’s environments.
Case-sensitive substring that must appear in the log message. May be repeated; all must match.
Maximum number of log lines to return, paging backward from the end of the window. Use 0 for no limit (every log line in the window). Not applicable with
--tail.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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
RE2 regular expression matched against the log message. Prefer
--includes and --excludes for plain substring matches.Shortcut for fetching logs from a relative time ago until now. Accepts a duration (e.g. ‘30m’, ‘1h30m’) or ‘
Nd’ (e.g. ‘3d’). Maximum ‘7d’. Mutually exclusive with --start and --end.Start of the log time range. 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. Default is 30 minutes before the end. Window must be at most 7 days.
Stream new logs as they arrive until the deployment leaves a runnable state or you interrupt with Ctrl-C. Cannot be combined with the time-range or filter flags. For machine-readable streaming, prefer
--output jsonl over --output json.Examples
Print logs for the production environment over the last hourFilter output with --jq
Stream just the log messages as a JSONL stream
Output
Text mode (--output text): One line per log record: “[YYYY-MM-DD HH:MM:SS]: (replica) message”.
JSON mode (--output json): payload type managementapi.Log.
metrics
--mode current for a snapshot, --mode summary to aggregate a window, or --mode series to plot values over time. Scope the window with --since or --start/--end (max 7 days; only applies to summary and series), and select metrics with one or more --metric flags. In series mode the window is split at each promotion so every point reflects the deployment(s) serving the environment at that time.
Options
End of the metrics time range. Accepts ISO 8601; values without a timezone designator are interpreted in the local timezone. If omitted, the server defaults the end to now. Window must be at most 7 days.
Name of the environment (e.g. production). Run ‘baseten model environment list’ to see a model’s environments.
Name of a metric to return; see https://docs.baseten.co/observability/export-metrics/supported-metrics for the available names. May be repeated. When omitted, a default set is returned.
Aggregation mode. ‘current’ returns an instantaneous snapshot at now; ‘summary’ aggregates the whole window into one value per metric; ‘series’ returns evenly-spaced points across the window.
--start/--end/--since are only meaningful for summary and series.One of: current, summary, seriesName of the model. Use
--team to disambiguate when the same name exists in multiple teams.Mutually exclusive with other flags in group model-ref.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Shortcut for a window from a relative time ago until now. Accepts a duration (e.g. ‘30m’, ‘1h30m’) or ‘
Nd’ (e.g. ‘3d’). Maximum ‘7d’. Mutually exclusive with --start and --end.Start of the metrics time range. 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. If omitted, the server defaults the start to one hour before the end. Window must be at most 7 days.
Examples
Show a current snapshot of the default metrics for the production environmentFilter output with --jq
Print the metric names returned
Output
Text mode (--output text): For current and summary, a table with columns METRIC, one column per label dimension (for example QUANTILE, STAT), and VALUE; summary counter values show “total (rate/s)”. For series, a sparkline per metric label set with its min-max range and end value, or a per-step table under --no-chart.
JSON mode (--output json): payload type managementapi.GetModelMetricsResponse.
The metrics response: metric_descriptors, index-mapped metric_values, the resolved mode, and the returned window.
update-autoscaling
baseten model environment describe to see the current values.
Options
Name of the environment (e.g. production). Run ‘baseten model environment list’ to see a model’s environments.
Maximum percentage of replicas that can be removed per autoscaling window (1-50). For example, 20 means at most 20% of replicas are removed per window.
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Raise the production environment’s replica boundsFilter output with --jq
Print the environment’s resulting minimum replica count
Output
Text mode (--output text): On success, prints “Updated autoscaling settings for environment name” to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.UpdateEnvironmentResponse.
update-promotion
--max-surge-percent and --max-unavailable-percent to positive values. Set the budget you want to disable to 0. These settings apply to future promotions into the environment.
Inspect promotion_settings in the JSON output from model environment describe.
Options
Name of the environment (e.g. production). Run ‘baseten model environment list’ to see a model’s environments.
Maximum percentage of the baseline replica count to provision as extra replicas across both deployments, including replicas still starting. Accepts integers from 0 to 100. Pass
0 to disable this budget; omit the flag to keep its current value. Both budgets can be positive in mixed mode. Configure rolling deployments.Maximum percentage of the baseline replica count that can be unavailable through planned replica replacement. Accepts integers from 0 to 50. Pass
0 to disable this budget; omit the flag to keep its current value. Both budgets can be positive in mixed mode. Configure rolling deployments.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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Whether to deploy on all promotions. Enabling this allows model code to safely handle environment-specific logic: when a deployment is promoted, a new deployment is created with a copy of the image. Pass
true or false explicitly; omit the flag to leave this setting unchanged.Whether the environment should rely on rolling deploy orchestration. Pass
true or false explicitly; omit the flag to leave this setting unchanged.Examples
Turn on rolling deploys and scale the outgoing deployment to zero<MODEL_ID> with your model’s ID and run the following command:
Filter output with --jq
Print the resulting cleanup strategy
Output
Text mode (--output text): On success, prints “Updated promotion settings for environment name” to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.UpdateEnvironmentResponse.
update-request-backpressure
--policy null to clear an existing policy and fall back to the default.
Run baseten model environment describe to see the current values.
Options
Name of the environment (e.g. production). Run ‘baseten model environment list’ to see a model’s environments.
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.Backpressure policy to apply. Pass null to clear an existing policy.One of:
queue-on-full, reject-on-full, nullUse a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Reject requests once the queue is fullFilter output with --jq
Print the resulting policy
Output
Text mode (--output text): The resulting policy, or “none” when no policy is set.
JSON mode (--output json): payload type managementapi.UpdateEnvironmentResponse.
environment autoscaling-schedule
A schedule scales an environment to a target replica count over a recurring or one-time window. Manage the schedules themselves and the timezone they share.create
--cadence selects the schedule’s shape. ‘daily’ and ‘hourly’ are recurring and need --weekdays and a minute window; ‘one-time’ runs once and needs --start-at and --end-at instead.
--min-replica and --max-replica are required. Any other autoscaling flag you omit is inherited from the environment while the schedule is active.
--timezone is required for the first schedule on an environment, since the timezone is shared by the whole collection and has no default. Afterwards it is optional and must match the existing one; use ‘update-settings’ to change it for every schedule at once.
Run ‘baseten model environment describe’ to see the current values.
Options
Shape of the schedule. Recurring schedules use
--weekdays and a minute window; one-time schedules use --start-at and --end-at.One of: daily, hourly, one-timeHour the window closes, in the collection timezone. Omit for an hourly schedule that runs every hour. Recurring schedules only.
Name of the environment (e.g. production). Run ‘baseten model environment list’ to see a model’s environments.
Maximum percentage of replicas that can be removed per autoscaling window (1-50). For example, 20 means at most 20% of replicas are removed per window.
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Inclusive start of the window, ISO 8601 (for example 2026-09-01T08:00). Values without a timezone designator are read in the local timezone. Must be in the future. One-time schedules only.
Hour the window opens, in the collection timezone. Omit for an hourly schedule that runs every hour. Recurring schedules only.
IANA timezone shared by every schedule on the environment, for example America/New_York. Required for the first schedule; afterwards it must match the existing one.
Weekdays the schedule runs, comma-separated. Recurring schedules only.One of:
monday, tuesday, wednesday, thursday, friday, saturday, sundayExamples
Scale up on weekday morningsFilter output with --jq
Print the ids of every schedule after the create
Output
Text mode (--output text): On success, prints “Created autoscaling schedule name” to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.UpdateEnvironmentResponse.
delete
Options
Name of the environment (e.g. production). Run ‘baseten model environment list’ to see a model’s environments.
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Stable identifier of the schedule, from ‘autoscaling-schedule list’.Mutually exclusive with other flags in group
schedule-ref.Name of the schedule, unique among the environment’s schedules.Mutually exclusive with other flags in group
schedule-ref.Examples
Delete a schedule by idFilter output with --jq
Print the ids that remain
Output
Text mode (--output text): On success, prints “Deleted autoscaling schedule id” to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.UpdateEnvironmentResponse.
list
Options
Name of the environment (e.g. production). Run ‘baseten model environment list’ to see a model’s environments.
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
List an environment’s schedulesFilter output with --jq
Print each schedule’s id and name
Output
Text mode (--output text): Table with columns: ID, NAME, CADENCE, ENABLED, WINDOW, REPLICAS. When no schedules exist, prints “No autoscaling schedules found.” to stderr.
JSON mode (--output json): payload type managementapi.EnvironmentAutoscalingSchedules.
update
--cadence to change a schedule’s shape. The new shape’s timing flags are then required, since a recurring window and a one-time interval have nothing in common to carry over; the name, enabled state, and autoscaling overrides carry over either way.
--timezone is not accepted here, because it belongs to the whole collection; use ‘update-settings’.
Options
New shape for the schedule. Changing it requires the new shape’s timing flags, since there is nothing to carry over.One of:
daily, hourly, one-timeWhether the schedule is enabled. Pass
true or false explicitly; omit the flag to leave this setting unchanged.Hour the window closes, in the collection timezone. Omit for an hourly schedule that runs every hour. Recurring schedules only.
Name of the environment (e.g. production). Run ‘baseten model environment list’ to see a model’s environments.
Maximum percentage of replicas that can be removed per autoscaling window (1-50). For example, 20 means at most 20% of replicas are removed per window.
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Stable identifier of the schedule, from ‘autoscaling-schedule list’.Mutually exclusive with other flags in group
schedule-ref.Name of the schedule, unique among the environment’s schedules.Mutually exclusive with other flags in group
schedule-ref.Inclusive start of the window, ISO 8601 (for example 2026-09-01T08:00). Values without a timezone designator are read in the local timezone. Must be in the future. One-time schedules only.
Hour the window opens, in the collection timezone. Omit for an hourly schedule that runs every hour. Recurring schedules only.
Weekdays the schedule runs, comma-separated. Recurring schedules only.One of:
monday, tuesday, wednesday, thursday, friday, saturday, sundayExamples
Raise a schedule’s replica floorFilter output with --jq
Print the resulting schedule names
Output
Text mode (--output text): On success, prints “Updated autoscaling schedule id” to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.UpdateEnvironmentResponse.
update-settings
Options
Name of the environment (e.g. production). Run ‘baseten model environment list’ to see a model’s environments.
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
IANA timezone to apply to every schedule on the environment, for example America/New_York.
Examples
Move every schedule to a new timezoneFilter output with --jq
Print the resulting timezone
Output
Text mode (--output text): On success, prints “Updated autoscaling schedule settings” to stderr; no stdout output.
JSON mode (--output json): payload type managementapi.UpdateEnvironmentResponse.
environment traffic-rule
PRE-RELEASE: Traffic routing rules are not GA yet. Their arguments, flags, and output may change.
model environment describe shows an environment’s active rules.
list
update and delete take.
Options
Name of the environment (e.g. production). Run ‘baseten model environment list’ to see a model’s environments.
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
List an environment’s rulesFilter output with --jq
Print each rule’s ID and percentage
Output
Text mode (--output text): Table with columns: ID, TYPE, TARGET, PERCENT, SAMPLING MODE, PROPAGATE CANCELLATION, EXPIRES. When no rules exist, prints “No traffic rules found.” to stderr.
JSON mode (--output json): Go output type managementapi.EnvironmentTrafficRouting.
create
--target-environment or --target-deployment-id. A target environment sends the shadow traffic to whichever deployment that environment is serving.
--sampling-mode random picks each request independently. --sampling-mode user-session keeps a whole session together, so every request in a sampled session is shadowed. --expires-at takes an ISO 8601 time such as 2026-11-02T18:00, at most 7 days out. --propagate-client-cancellation decides whether a shadow request is cancelled when the original client disconnects, and it needs an explicit true or false.
Options
Name of the environment (e.g. production). Run ‘baseten model environment list’ to see a model’s environments.
When the rule stops, ISO 8601 (for example 2026-10-08T18:00), at most 7 days out. Values without a timezone designator are read in the local timezone.
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
How requests are picked for shadowing. random picks each request independently. user-session keeps a whole session together.One of:
random, user-sessionName of the target environment. Traffic goes to whichever deployment the environment is serving.Mutually exclusive with other flags in group
target.Rule type. A shadow rule sends a copy of the environment’s traffic to its target.One of:
shadowExamples
Shadow 25% of production’s traffic to stagingFilter output with --jq
Print the IDs of the environment’s active rules after the create
Output
Text mode (--output text): Prints “Created traffic rule” to stderr; nothing on stdout.
JSON mode (--output json): Go output type managementapi.UpdateEnvironmentResponse.
update
--rule-id. Only the flags you pass change; the command reads the environment, merges your flags into the existing rule, and writes it back, because the API replaces a rule wholesale.
Options
Name of the environment (e.g. production). Run ‘baseten model environment list’ to see a model’s environments.
New time the rule stops, ISO 8601 (for example 2026-10-08T18:00), at most 7 days out. Values without a timezone designator are read in the local timezone.
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
ID of the rule. Run ‘baseten model environment traffic-rule list’ to see the environment’s rules.
Examples
Raise the percentage of traffic a rule shadowsFilter output with --jq
Print each active rule’s percentage after the update
Output
Text mode (--output text): Prints “Updated traffic rule id” to stderr; nothing on stdout.
JSON mode (--output json): Go output type managementapi.UpdateEnvironmentResponse.
delete
--rule-id.
Prompts for yes/no confirmation. Pass --yes to skip the prompt. When stdin is not a terminal, --yes is required.
Options
Name of the environment (e.g. production). Run ‘baseten model environment list’ to see a model’s environments.
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
ID of the rule. Run ‘baseten model environment traffic-rule list’ to see the environment’s rules.
Examples
Delete a ruleFilter output with --jq
Print the IDs of the rules that remain
Output
Text mode (--output text): Prints “Deleted traffic rule id” to stderr; nothing on stdout.
JSON mode (--output json): Go output type managementapi.UpdateEnvironmentResponse.
image
Build a local Docker image, or just its Docker build context, from a model directory. These commands run entirely locally: they shell out to the truss CLI (via ‘uv’) to generate the build context and to ‘docker’ to build the image. They need no authentication and make no Baseten API calls. ‘uv’ must be on PATH; ‘build’ also requires ‘docker’.build
--dir to point at a model directory elsewhere. The build context is written to a temporary directory that is removed afterward unless --build-dir is given.
Any arguments after ’—’ are passed through verbatim to ‘docker build’. If you supply your own --iidfile there, it is honored and used to report the image ID; otherwise one is injected internally.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Run this truss executable instead of fetching one with uv, e.g. a virtualenv’s bin/truss. A value with no path separator is looked up on PATH, so ‘
--truss-executable truss’ runs the truss you installed. Defaults to BASETEN_TRUSS_EXECUTABLE.Version of truss to fetch and run with ‘uv tool run’, e.g. 0.18.26. Defaults to BASETEN_TRUSS_VERSION, or the latest release. Mutually exclusive with
--truss-executable.Examples
Build the current directory into a local Docker imageFilter output with --jq
Print the built image ID
Output
Text mode (--output text): Build progress from truss and docker is streamed to stderr. On success a one-line summary is printed to stdout.
JSON mode (--output json): payload type cmd.ModelImageBuildResult.
Under --output json, stdout is the {image_id, tag} result. image_id is empty when it cannot be resolved (e.g. a custom buildx builder that does not write the iidfile).
prepare
--build-dir, without building an image.
The current directory is used by default; pass --dir to point at a model directory elsewhere. The resulting directory is self-contained and can be built with ‘docker build build-dir’.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Run this truss executable instead of fetching one with uv, e.g. a virtualenv’s bin/truss. A value with no path separator is looked up on PATH, so ‘
--truss-executable truss’ runs the truss you installed. Defaults to BASETEN_TRUSS_EXECUTABLE.Version of truss to fetch and run with ‘uv tool run’, e.g. 0.18.26. Defaults to BASETEN_TRUSS_VERSION, or the latest release. Mutually exclusive with
--truss-executable.Examples
Write the current directory’s build context to ./ctxFilter output with --jq
Print the generated Dockerfile path
Output
Text mode (--output text): Progress from truss is streamed to stderr. On success a one-line summary is printed to stdout.
JSON mode (--output json): payload type cmd.ModelImagePrepareResult.
Under --output json, stdout is the {build_dir, dockerfile} result with absolute paths.