Command line (strand)

The Python SDK includes the strand command for running the upload-to-results workflow without a script. It uses the same strand.Client as the library and MCP tools. Each command maps one-to-one to an SDK method and uses the same argument names.

Install

pip install strand-sdk
# with the extras needed to open results as AnnData:
pip install "strand-sdk[anndata]"

Installing the package puts strand on your PATH.

strand --help
strand --version

Configuration

The CLI reads the same environment variables as strand.Client().

Variable	Purpose	Default
`STRAND_API_KEY`	API key (`sk-strand-…`). Required.	none
`STRAND_BASE_URL`	API base URL.	`https://app.strandai.com`

export STRAND_API_KEY="sk-strand-…"

Generate a key at app.strandai.com. Commands print machine-readable JSON to stdout, so they compose with jq and shell pipelines. On failure the CLI writes a one-line message to stderr and exits with a non-zero status.

End-to-end run

# 1. Upload a slide. Capture the sample id from its current ingest snapshot.
sample_id=$(strand upload biopsy.svs --mpp 0.25 | jq -r .id)

# 2. Wait until automatic ingest makes the sample prediction-ready.
while :; do
  status=$(strand samples get "$sample_id" | jq -r .status)
  case "$status" in
    ready) break ;;
    *failed) echo "ingest failed: $status" >&2; exit 1 ;;
  esac
  sleep 2
done

# 3. Price the exact request without creating a job or reserving credits.
strand predict "$sample_id" --markers CD3e,CD8,PanCK --dry-run | jq

# 4. Submit the same prediction and capture its job id.
job_id=$(strand predict "$sample_id" --markers CD3e,CD8,PanCK | jq -r .job_id)

# 5. Wait for a terminal status (SSE with polling fallback).
strand wait "$job_id" --timeout 1800

# 6. Download OME-Zarr results or a pyramidal OME-TIFF.
strand results "$job_id" --out ./results/
strand export "$job_id" --format ome-tiff --out ./result.ome.tiff --timeout 1800

Commands

`strand markers`

List the markers your account can request (credit-free). The names printed are exactly what strand predict will accept for your account.

strand markers

Wraps client.markers.list().

`strand upload`

Upload a local whole-slide image. The command performs a resumable chunked upload and prints the sample’s current ingest state. Dimensions may still be absent while ingest preprocessing continues.

strand upload biopsy.svs
strand upload biopsy.svs --mpp 0.25
strand upload biopsy.svs --content-type image/tiff --if-not-exists

Option	Description
`--mpp FLOAT`	Microns per pixel for the slide (isotropic). Persisted at creation and takes precedence over the slide’s own calibrated scale.
`--content-type TEXT`	MIME type override. Auto-detected from the file extension when omitted.
`--if-not-exists`	Dedup by content hash. Skips the byte upload when a matching sample already exists in your org.

Wraps client.uploads.upload_file(...). Before an immediate dry run or submission, poll strand samples get SAMPLE_ID until status is ready.

`strand predict`

Price or submit a prediction against an uploaded sample. --dry-run prints the full estimate without creating a job or reserving credits. The default submission reserves credits and prints the job id.

strand predict <sample-id> --markers CD3e,CD8,PanCK --dry-run
strand predict <sample-id> --markers CD3e,CD8,PanCK
strand predict <sample-id> -m CD8,Ki67 --model v0.7

Argument / option	Description
`SAMPLE_ID`	Sample id returned by `strand upload`.
`--markers`, `-m`	Comma-separated marker names like `CD3e,CD8,PanCK`.
`--model TEXT`	Lattice version. The server picks the current default when omitted.
`--dry-run`	Validate and price the request without creating a job or reserving credits.

Wraps client.predict.submit(..., dry_run=...). See Markers for the predictable panel.

`strand status`

Print a point-in-time status snapshot for a job: state, progress, markers, and the served model.

strand status <job-id>

Wraps client.jobs.get(<job-id>).status.

`strand wait`

Wait for a terminal job snapshot. The command prefers the job’s SSE stream and falls back to status polling if the stream disconnects.

strand wait <job-id>
strand wait <job-id> --timeout 1800 --poll-interval 2

Option	Description
`--timeout FLOAT`	Maximum seconds to wait. Omit it to wait indefinitely.
`--poll-interval FLOAT`	Seconds between status requests when polling is needed. Defaults to 2.

Wraps client.jobs.get(<job-id>).wait(...). A failed job or elapsed timeout prints an error and exits non-zero; completed, partially failed, and cancelled snapshots print as JSON.

`strand cancel`

Cancel an eligible in-flight job, release its credit reservation, and print the refreshed post-cancel snapshot.

strand cancel <job-id>

Wraps client.jobs.get(<job-id>).cancel().

`strand results`

Download a completed job’s OME-Zarr result tree to a local directory. Streams the files through the API-key result proxy.

strand results <job-id> --out ./results/

Option	Description
`--out`, `-o`	Directory to write into. Created if missing. Defaults to `./results`.

Wraps client.jobs.get(<job-id>).download_results(dir).

`strand export`

Request or reuse a generated result export, wait until it is ready, write it to the required destination path, and print that path.

strand export <job-id> --format ome-tiff --out ./result.ome.tiff
strand export <job-id> --format ome-zarr-zip --out ./result.zip --include-segmentation

Option	Description
`--format`	Required: `ome-tiff` or `ome-zarr-zip`. Native OME-Zarr uses `strand results`.
`--out`, `-o`	Required destination file. Parent directories are created.
`--include-segmentation`	Attach the latest mask/cell manifest to the export response.
`--timeout FLOAT`	Maximum seconds to wait for export. Omit it to wait indefinitely.
`--poll-interval FLOAT`	Seconds between export-status requests. Defaults to 2.

Wraps client.jobs.get(<job-id>).download_export(...).

`strand samples list`

List owned samples, the public cohort, or both through one cursor-paginated surface. The JSON envelope contains items and next_cursor; every item has canonical id and an ownership discriminator.

strand samples list
strand samples list --scope public --limit 50
strand samples list --scope all --cursor <next-cursor> --tag trial-042

Option	Description
`--scope [mine\|public\|all]`	Sample scope. Defaults to `mine`.
`--limit INTEGER`	Page size (API range 1 to 100). Defaults to 48.
`--cursor TEXT`	Pagination cursor from a prior response’s `next_cursor`.
`--tag TEXT`	Exact sample-tag filter.

Wraps client.samples.list(...).

`strand samples get`

Read an owned or public sample using its canonical id. Owned output includes jobs and job_count. Public output includes geometry and marker channels. --download mirrors a public sample’s OME-Zarr store.

strand samples get <sample-id>
strand samples get <public-id> --download ./public-sample.zarr

Wraps client.samples.get(...).

`strand samples patch`

Patch an owned sample’s display name, complete tag set, and/or physical scale. Omitted options are not sent.

strand samples patch <sample-id> --name "Trial 42 baseline"
strand samples patch <sample-id> --tag trial-042 --tag baseline --mpp 0.26
strand samples patch <sample-id> --clear-name --clear-tags

Option	Description
`--name TEXT`	Set the display name. Mutually exclusive with `--clear-name`.
`--clear-name`	Revert the display name to the filename.
`--tag TEXT`	Complete desired tag set; repeat for multiple tags. Mutually exclusive with `--clear-tags`.
`--clear-tags`	Clear all editable tags.
`--mpp FLOAT`	Set isotropic microns per pixel.

Wraps client.samples.patch(...).

`strand uploads list`

List resumable upload records for your organization. This is distinct from the scoped sample catalog.

strand uploads list
strand uploads list --limit 50 --cursor <next-cursor>

Option	Description
`--limit INTEGER`	Page size (1 to 200). Defaults to 100.
`--cursor TEXT`	Pagination cursor from a prior response’s `next_cursor`.

Wraps client.uploads.list(...).

Developer workflows

Command line (strand)

Install

Configuration

End-to-end run

Commands

`strand markers`

`strand upload`

`strand predict`

`strand status`

`strand wait`

`strand cancel`

`strand results`

`strand export`

`strand samples list`

`strand samples get`

`strand samples patch`

`strand uploads list`

See also

​Install

​Configuration

​End-to-end run

​Commands

​strand markers

​strand upload

​strand predict

​strand status

​strand wait

​strand cancel

​strand results

​strand export

​strand samples list

​strand samples get

​strand samples patch

​strand uploads list

​See also

Install

Configuration

End-to-end run

Commands

`strand markers`

`strand upload`

`strand predict`

`strand status`

`strand wait`

`strand cancel`

`strand results`

`strand export`

`strand samples list`

`strand samples get`

`strand samples patch`

`strand uploads list`

See also