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

# CLI

> Run resumable S3 batches, inspect jobs, retrieve results, and manage the local cache.

# CLI

The CLI is installed with the Python SDK. See
[Authentication](/reference/authentication) for environment configuration.
Every API command uses the configured deployment's `/v1` routes. After logging
in, use `sutro quotas` to verify that the deployment can reach Batch.

| Command | Purpose |
| - | - |
| `sutro login` | Validate and save a deployment URL and API key. |
| `sutro set-api-url URL` | Change the saved deployment URL; changing deployments clears the saved key. |
| `sutro quotas` | Show row and token quotas by priority. |
| `sutro functions run NAME --input JSON` | [Run a Function](/functions/run) on one input and print the JSON response. `--input` takes a JSON object or `@path/to/input.json`. |
| `sutro batch-run --function NAME --dataset S3_URI -o OUTPUT.parquet` | Run a published Function on one S3 object, watch, and download with durable recovery. |
| `sutro jobs resume JOB_ID -o OUTPUT.parquet` | Watch/download an existing job without submitting or accessing the source object. |
| `sutro jobs list` | Show the 25 most recent jobs. |
| `sutro jobs list --all` | Include all historical, cancelled, and failed jobs. |
| `sutro jobs status JOB_ID` | Show one job's status. |
| `sutro jobs results JOB_ID` | Print results. |
| `sutro jobs attach JOB_ID` | Stream progress for a running job. |
| `sutro jobs attach --latest` | Attach to the most recent job. |
| `sutro jobs cancel JOB_ID` | Request cancellation. |
| `sutro cache show` | Show locally cached job results. |
| `sutro cache clear` | Clear the local results cache. |
| `sutro docs` | Open the documentation. |

## Resumable S3 batches

Configure deployment credentials with `sutro login` or environment variables,
and configure local AWS credentials. On macOS or Linux, run:

```bash theme={null}
sutro batch-run \
  --function support-agent-judge \
  --dataset s3://my-bucket/evaluations/input.jsonl \
  -o results.parquet
```

The input is one CSV, Parquet, or JSONL object whose fields match the published
Function. The command uses priority 1 and the Function's sampling settings.
Upgrade the SDK and deployment for resumable submission support; older
deployments are rejected before submission.

Repeat the same command after Ctrl-C, a lost connection, or an interrupted
download. Keep `results.parquet.sutro.json` and partial-download files. The
receipt preserves the submission key and job ID; the output path also locates
that receipt. To change destination or recover on another machine, use:

```bash theme={null}
sutro jobs resume job-12345678-1234-1234-1234-1234567890ab -o recovered.parquet
```

`jobs resume` needs deployment credentials but no source AWS credentials.
Ctrl-C and timeout stop local watching without cancelling remote work.
Failed or partial jobs stop without replacement submissions or partial output.

| Option | Behavior |
| - | - |
| `--output-file-name PATH`, `-o PATH` | Required local `.parquet` destination for both commands. |
| `--id-column NAME` | `batch-run` only: preserve a separate scalar source ID column. |
| `--new-run` | `batch-run` only: archive the receipt and explicitly submit new work, which can incur compute charges. |
| `--overwrite` | Allow replacing output; this alone does not submit a new job. |
| `--timeout SECONDS` | Submission/watch limit; defaults to 86400 seconds. Remote work continues afterward. |
| `--no-unpack-json` | Retain `inference_result` rather than unpacking structured fields. |
| `--include-inputs` | Include rendered model inputs; original dataset columns are not automatically joined. |

AWS credentials stay local; the CLI pins the object's version, ETag and size
before signing its GET URL. Unversioned objects must remain unchanged until
ingestion finishes. JSONL uses one UTF-8 object per nonblank line, no duplicate
keys and at most 4 MiB per line. Directories, globs and compressed CSV/JSONL are
unsupported. The command requires macOS or Linux.

Receipts bind the deployment and authenticated owner; same-owner key rotation
can resume. An older receipt with no owner ID and no visible reservation stops
without posting. Keep the original owner's key or use a known job ID.

Output uses SDK result conventions: representable JSON objects expand into
columns, nested values remain nested, and IDs/confidence are preserved.
Otherwise output remains `inference_result`. Use `--no-unpack-json` for field
collisions. For Python, use the existing
[`batch_run_function()`](/reference/python-sdk/functions#retry-safe-s3-submission)
and [job methods](/reference/python-sdk/job-methods).

## Result options

```bash theme={null}
sutro jobs results JOB_ID \
  --include-inputs \
  --include-cumulative-logprobs \
  --save \
  --save-format parquet
```

`--save-format` accepts `parquet` or `csv` and defaults to `parquet`. Without
`--save`, results print to the terminal.

`sutro set-base-url` remains as a hidden deprecated alias for
`sutro set-api-url`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.