CLI Reference - Simplismart

The Simplismart CLI provides command-line access to manage model repositories, deployments, and secrets.

Installation

After installing the SDK, the CLI is available as the simplismart command:

pip install simplismart-sdk

Global Options

These options apply to all CLI commands:

simplismart [global options] <command> [subcommand] [options]

Option	Description	Default
`--pg-token TOKEN`	Playground token	Falls back to `SIMPLISMART_PG_TOKEN` env var
`--base-url URL`	API base URL	`https://api.app.simplismart.ai`
`--timeout SECONDS`	Request timeout	`300`
`--trace-id ID`	Optional trace/correlation ID	Generated per request

Model Repos Commands

Manage model repositories using simplismart model-repos.

List Model Repos

Lists model repositories with optional filtering.

simplismart model-repos list [options]

Option	Description
`--offset N`	Pagination offset (default: 0)
`--count N`	Page size (default: 5)
`--model-id UUID`	Fetch specific model repo by ID
`--name NAME`	Filter by model name (contains match)
`--status STATUS`	Filter by status
`--model-type TYPE`	Filter by model type
`--created-by EMAIL`	Filter by creator email

Expected output

{
  "limit": 5,
  "offset": 0,
  "count": 50,
  "results": [
    {
      "uuid": "<MODEL_REPO_ID>",
      "name": "whisper-nemo-diarization",
      "source_type": "docker_hub",
      "source_url": "simplismart/whisper-nemo-diarization:latest",
      "is_byom": true,
      "accelerator": null,
      "runtime_gpus": 1,
      "byom": {
        "image": "simplismart/MODEL-NAME:latest",
        "registry": "simplismart/REGISTRY-NAME",
        "tag": "latest"
      },
      "secrets": {
        "source_secret": {
          "uuid": "<SECRET_ID>",
          "name": "<SECRET_NAME>"
        }
      },
      "status": "SUCCESS",
      "model_type": "byom",
      "env": {},
      "created_at": "2026-03-02T11:52:16.925151Z",
      "updated_at": "2026-03-02T11:52:16.925162Z",
      "org_id": "<ORG_ID>",
      "healthcheck": {
        "path": "/health",
        "port": 8000,
        "periodSeconds": 10,
        "timeoutSeconds": 5,
        "initialDelaySeconds": 30
      },
      "ports": {
        "http": {
          "port": 8000
        }
      },
      "metrics_path": [],
      "deployment_custom_configuration": {
        "command": []
      }
    }
  ]
}

Status Options

Value	Description
`SUCCESS`	Model repo is ready
`FAILED`	Model repo creation failed
`DELETED`	Model repo has been deleted
`PROGRESSING`	Model repo is being created

Example:

# List all model repos
simplismart model-repos list --offset 0 --count 5

# Filter by status and name
simplismart model-repos list --status SUCCESS --name vision

# Get specific model repo
simplismart model-repos list --model-id <MODEL_REPO_ID>

Get Model Repo

Gets details of a specific model repository.

simplismart model-repos get [options]

Option	Description
`--model-id UUID`	Model repo UUID (required)

Example:

simplismart model-repos get --model-id <MODEL_REPO_ID>

Expected output

{
  "uuid": "<MODEL_REPO_ID>",
  "name": "whisper-nemo-diarization",
  "source_type": "docker_hub",
  "source_url": "simplismart/MODEL_NAME:latest",
  "is_byom": true,
  "accelerator": null,
  "runtime_gpus": 1,
  "byom": {
      "image": "simplismart/MODEL-NAME:latest",
      "registry": "simplismart/REGISTRY-NAME",
    "tag": "latest"
  },
  "secrets": {
    "source_secret": {
      "uuid": "<SECRET_ID>",
      "name": "<SECRET_NAME>"
    }
  },
  "status": "SUCCESS",
  "model_type": "byom",
  "env": {},
  "created_at": "2026-03-02T11:52:16.925151Z",
  "updated_at": "2026-03-02T11:52:16.925162Z",
  "org_id": "<ORG_ID>",
  "healthcheck": {
    "path": "/health",
    "port": 8000,
    "periodSeconds": 10,
    "timeoutSeconds": 5,
    "initialDelaySeconds": 30
  },
  "ports": {
    "http": {
      "port": 8000
    }
  },
  "metrics_path": [],
  "deployment_custom_configuration": {
    "command": []
  }
}

Get Model Profiles

Generates/resolves the model profile from a source type and path. Returns the optimization combinations available for that model (quantizations, machines, and parallelism options).

simplismart model-repos profiles [options]

Option	Description
`--type TYPE`	Source type (required) - e.g., `hf`, `s3`, `azure_blob`
`--path PATH`	Source path (required)
`--secret-id UUID`	Secret UUID (optional)

Example:

simplismart model-repos profiles --type hf --path meta-llama/Llama-3.1-8B-Instruct

Expected output

{
  "profile": {
    "model_info": {
      "type": "llm",
      "architecture": "LlamaForCausalLM",
      "param_size": "8030261248",
      "default_quantization": "float16"
    },
    "quantizations": {
      "float16": {
        "machines": [
          "nvidia-a100-40gb",
          "nvidia-a100-80gb",
          "nvidia-h100",
          "nvidia-l40s"
        ]
      },
      "fp8": {
        "machines": [
          "nvidia-h100",
          "nvidia-h100-pcie",
          "nvidia-h100-sxm5"
        ]
      },
      "int4": {
        "machines": [
          "nvidia-a100-40gb",
          "nvidia-a10g",
          "nvidia-h100",
          "nvidia-l4",
          "nvidia-l40s",
          "nvidia-tesla-t4"
        ]
      }
    },
    "combinations": [
      {
        "quantization": "float16",
        "machine": "nvidia-h100",
        "tensor_parallelism": [1, 2, 4, 8],
        "data_parallelism": [1],
        "pipeline_parallelism": [1],
        "expert_parallelism": [1]
      }
    ]
  }
}

Output: JSON with a profile object containing:

model_info — type, architecture, param_size, default_quantization
quantizations — map of quantization (e.g. float16, fp8, int4) to list of supported machines
combinations — list of valid (quantization, machine, parallelism) combinations; each has quantization, machine, tensor_parallelism, data_parallelism, pipeline_parallelism, expert_parallelism (each a list of allowed values)

Bring Your Own Container Model Repo

Bring your own container.

simplismart model-repos create-container [options]

Option	Description
`--name NAME`	Model repo name (required)
`--source-type TYPE`	Source type (required) - `docker_hub`, `depot`, `nvidiadockersecret`
`--runtime-gpus N`	Runtime GPU count (required)
`--source-secret UUID`	Source secret UUID (required for registry sources)
`--registry-path PATH`	Registry path/repo (required)
`--docker-tag TAG`	Image tag (required)
`--env KEY=VALUE`	Environment variable (can be repeated)
`--healthcheck JSON/@file`	JSON or file path for healthcheck
`--ports JSON/@file`	JSON or file path for ports
`--metrics-path JSON/@file`	JSON array or file path for metrics paths
`--deployment-custom-configuration JSON/@file`	Custom deployment config

Example:

simplismart model-repos create-container \
  --name vision-container \
  --source-type docker_hub \
  --runtime-gpus 1 \
  --source-secret <SECRET_ID> \
  --registry-path org/vision \
  --docker-tag v1.2.3

Create Private Compile Model Repo

Creates a private compile model repository: the platform compiles the model from a source (e.g. Hugging Face) using config files for model, optimisation, and pipeline.

simplismart model-repos create-private-compile [options]

Option	Description
`--name NAME`	Model repo name (required)
`--avatar-url URL`	Avatar image URL (required)
`--avatar-font-color COLOR`	Avatar font color
`--avatar-background-color COLOR`	Avatar background color
`--source-type TYPE`	Source type (required) - e.g. `huggingface`
`--source-url URL`	Source path/URL (required) - e.g. HF repo id
`--mode MODE`	Compilation mode (default: `public_hf`) - e.g. `public_hf`, `private_hf`, `aws`, `gcp`, `public_url`, `simplismart`
`--model-class CLASS`	Model class (required) - e.g. `LlamaForCausalLM`
`--accelerator-type TYPE`	Accelerator type (required) - e.g. `nvidia-h100`
`--accelerator-count N`	Accelerator count (default: 0)
`--org-id UUID`	Org UUID (optional if inferred from PG token)
`--cloud-account UUID`	Cloud account UUID
`--source-secret UUID`	Secret UUID for source access
`--lora-secret UUID`	LoRA secret UUID
`--description TEXT`	Description
`--short-description TEXT`	Short description
`--dropdown-description TEXT`	Dropdown description
`--machine-type TYPE`	Machine type
`--region REGION`	Region
`--resource-group GROUP`	Resource group
`--processing-mode MODE`	One of: `SYNC`, `ASYNC`, `REALTIME_ASYNC`
`--model-family FAMILY`	Model family
`--env KEY=VALUE`	Environment variable (repeatable)
`--model-config JSON/@file`	Model config
`--optimisation-config JSON/@file`	Optimisation config
`--pipeline-config JSON/@file`	Pipeline config
`--tasks JSON/@file`	Tasks list
`--tags JSON/@file`	Tags object
`--output-metadata JSON/@file`	Output metadata
`--additional-details JSON/@file`	Additional details

Example:

simplismart model-repos create-private-compile \
  --name llama-sdk-cli \
  --avatar-url "https://ui-avatars.com/api/?name=llama" \
  --source-type huggingface \
  --source-url meta-llama/Llama-3.2-1B-Instruct \
  --model-class LlamaForCausalLM \
  --accelerator-type nvidia-h100 \
  --model-config @examples/private-compile-sample/model_config.json \
  --optimisation-config @examples/private-compile-sample/optimisation_config.json \
  --pipeline-config @examples/private-compile-sample/pipeline_config.json

Config files: See the SDK reference for the structure of model_config.json, optimisation_config.json, and pipeline_config.json. Example output

{
  "uuid": "<MODEL_REPO_ID>",
  "created_at": "2026-03-02T16:07:31.776954Z",
  "updated_at": "2026-03-02T16:07:31.776967Z",
  "org": "<ORG_ID>",
  "is_public": false,
  "is_deployable": true,
  "name": "llama-sdk-cli",
  "is_deleted": false,
  "deleted_at": null,
  "avatar": {
    "uuid": "<AVATAR_ID>",
    "image_url": "<IMG_URL>",
    "font_color": "#000000",
    "background_color": "#f3f3f3"
  },
  "model_class": "LlamaForCausalLM",
  "master_model_class": "llm",
  "env": {},
  "model_type": "platform",
  "tags": [],
  "short_description": "",
  "source_type": "huggingface",
  "source_url": "meta-llama/Llama-3.2-1B-Instruct",
  "gpu_count": 1,
  "is_dynamo": false,
  "status": "PENDING",
  "logs_pod_hostname": null
}

Full examples are in the Simplismart SDK example repo.

Delete Model Repo

Deletes a model repository.

simplismart model-repos delete [options]

Option	Description
`--model-id UUID`	Model repo UUID (required)

Example:

simplismart model-repos delete --model-id <MODEL_REPO_ID>

Example Output

{"status": "deleted", "model_id": "<MODEL_REPO_ID>"}

Deployments Commands

Manage deployments using simplismart deployments.

List Deployments

Lists deployments with optional filtering.

simplismart deployments list [options]

Option	Description
`--model-repo-id UUID`	Filter by model repo UUID
`--status STATUS`	Filter by status
`--offset N`	Pagination offset (default: 0)
`--count N`	Page size (default: 20)

Status Options

Value	Description
`DEPLOYED`	Deployment is running
`PENDING`	Deployment is being created
`FAILED`	Deployment failed
`STOPPED`	Deployment is stopped
`DELETED`	Deployment has been deleted

Example:

# List all deployments
simplismart deployments list --offset 0 --count 20

# Filter by status
simplismart deployments list --status DEPLOYED --offset 0 --count 20

# Filter by model repo
simplismart deployments list --model-repo-id <MODEL_REPO_ID> --status FAILED

Expected output

[
  {
    "deployment_id": "<DEPLOYMENT_ID>",
    "deployment_name": "whisper-nemo-diarization",
    "model_repo_id": "<MODEL_REPO_ID>",
    "model_repo_name": "whisper-nemo-diarization",
    "model_type": "unknown",
    "accelerator_type": ["nvidia-h100"],
    "accelerator_count": 1,
    "status": "DEPLOYED"
  },
  {
    "deployment_id": "<DEPLOYMENT_ID>",
    "deployment_name": "Gemma-3-4B",
    "model_repo_id": "<MODEL_REPO_ID>",
    "model_repo_name": "gemma-3-4b-optim-v2",
    "model_type": "llm",
    "accelerator_type": ["nvidia-h100"],
    "accelerator_count": 1,
    "status": "DEPLOYED"
  }
]

Create Deployment

Creates a deployment for a model repo.

simplismart deployments create [options]

Option	Description
`--model-repo UUID`	Model repo UUID (required)
`--org UUID`	Organization UUID (required)
`--gpu-id ID`	GPU type (required) - e.g., `nvidia-h100`, `A10`
`--name NAME`	Deployment name (required)
`--min-pod-replicas N`	Minimum pod replicas (required)
`--max-pod-replicas N`	Maximum pod replicas (required)
`--autoscale-config JSON/@file`	Autoscaling config (required)
`--env-variables JSON/@file`	Environment variables
`--deployment-custom-configuration JSON/@file`	Custom deployment config
`--healthcheck JSON/@file`	Health check config
`--ports JSON/@file`	Port mappings
`--metrics-path JSON/@file`	Metrics paths
`--persistent-volume-claims JSON/@file`	PVC configurations
`--fast-scaleup`	Enable fast scale up
`--deployment-tag TAG`	Deployment tag

Example:

# Create deployment
simplismart deployments create-private \
  --model-repo <MODEL_REPO_ID> \
  --org "$ORG_ID" \
  --gpu-id nvidia-h100 \
  --name vision-deploy \
  --min-pod-replicas 1 \
  --max-pod-replicas 2 \
  --autoscale-config @autoscale.json

Where autoscale.json contains:

{
  "targets": [
    {"metric": "gpu", "target": 80}
  ]
}

Get Deployment

Gets deployment details by ID.

simplismart deployments get [options]

Option	Description
`--deployment-id UUID`	Deployment UUID (required)

Example:

simplismart deployments get --deployment-id <DEPLOYMENT_ID>

Expected output Returns a single deployment object with full details (e.g. deployment_id, deployment_name, model_repo_id, model_repo_name, status, accelerator_type, accelerator_count, and other configuration fields).

{
  "uuid": "<DEPLOYMENT_UUID>",
  "avatar": {
    ...
  },
  "created_by": {
    ...
  },
  "persistent_volume_claims": [],
  "autoscale_config": {
    "targets": [
      {
        "unit": "%",
        "metric": "cpu",
        "target": 80,
        "description": "Average CPU usage across all pods"
      }
    ]
  },
  "deployment_custom_configuration": {
    "command": []
  },
  "ports": {
    "http": {
      "port": 8000
    }
  },
  "healthcheck": {
    "path": "/health",
    "port": 8000,
    "initialDelaySeconds": 30,
    "periodSeconds": 10,
    "timeoutSeconds": 5
  },
  "env_variables": {},
  "metrics_path": [],
  "metrics_http_method_overrides": {},
  "created_at": "2026-03-02T11:53:05.744416Z",
  "updated_at": "2026-03-02T12:05:17.018284Z",
  "is_public": false,
  "name": "whisper-nemo-diarization",
  "display_name": "whisper-nemo-diarization",
  "proxy_name": "",
  "status": "DEPLOYED",
  "slug": "fi0pjr7jaf",
  "autoscaling": true,
  "min_pod_replicas": 1,
  "max_pod_replicas": 8,
  "scale_to_zero_enabled": false,
  "model_cloud": "",
  "accelerator_type": "nvidia-h100",
  "accelerator_request": 1.0,
  "accelerator_limit": 1.0,
  "cpu_request": 23.0,
  "cpu_limit": 23.0,
  "memory_request": 190.0,
  "memory_limit": 190.0,
  "node_affinity": "none",
  "ended_at": null,
  "image_url": null,
  "tags": null,
  "proxy_url": "<PROXY_URL>",
  "api_details": {},
  "input_configuration": {},
  "deleted_at": null,
  "deployment_details": {},
  "advanced_configuration": {},
  "extra_details": {
    "deployment_tag": "production",
    "deletion_retry_count": 0
  },
  "external_deployment_id": null,
  "is_deployable": true,
  "model_output_type": "",
  "paused_at": null,
  "resumed_at": null,
  "async_deployment_type": "SYNC",
  "has_custom_proxy": false,
  "is_private_request_tracking_enabled": false,
  "is_privately_deployed": true,
  "status_description": null,
  "image_prepuller": false,
  "is_warmpool_deployment": false,
  "additional_tags": {},
  "cluster_selection_logic": [
    ...
  ],
  "org": "<ORG_ID>",
  "updated_by": null,
  "model_repo": "<MODEL_REPO_ID>",
  "cluster": "<CLUSTER_ID>",
  "pricing_catalog": null,
  "additional_usage_details": null,
  "input_volume_mounts": null,
  "output_volume_mounts": null,
  "source_secret": null,
  "deployment_config": null,
  "pricing_config": null,
  "node_groups": [
    "<NODE_GROUP_ID>"
  ]
}

Update Deployment

Updates deployment configuration.

simplismart deployments update [options]

Option	Description
`--deployment-id UUID`	Deployment UUID (required)
`--payload JSON/@file`	JSON object with editable fields (required)

Example:

simplismart deployments update --deployment-id <DEPLOYMENT_ID> --payload @edit-payload.json

Stop Deployment

Stops a running deployment.

simplismart deployments stop [options]

Option	Description
`--deployment-id UUID`	Deployment UUID (required)

Example:

simplismart deployments stop --deployment-id <DEPLOYMENT_ID>

Start Deployment

Starts a stopped deployment.

simplismart deployments start [options]

Option	Description
`--deployment-id UUID`	Deployment UUID (required)

Example:

simplismart deployments start --deployment-id <DEPLOYMENT_ID>

Scale Deployment

Updates deployment autoscaling configuration.

simplismart deployments scale [options]

Option	Description
`--deployment-id UUID`	Deployment UUID (required)
`--min-replicas N`	Minimum replicas (required)
`--max-replicas N`	Maximum replicas (required)

Example:

simplismart deployments scale \
  --deployment-id <DEPLOYMENT_ID> \
  --min-replicas 1 \
  --max-replicas 3

Delete Deployment

Deletes a deployment.

simplismart deployments delete [options]

Option	Description
`--deployment-id UUID`	Deployment UUID (required)

Example:

simplismart deployments delete --deployment-id <DEPLOYMENT_ID>

Secrets Commands

Manage secrets using simplismart secrets.

Create Secret

Creates a secret for an organization.

simplismart secrets create [options]

Option	Description
`--name NAME`	Secret name (required)
`--secret-type TYPE`	Secret type (required) - e.g., `docker_hub`
`--data JSON/@file`	Secret data as JSON (required)

Example:

simplismart secrets create \
  --name demo-secret \
  --secret-type docker_hub \
  --data @secret-data.json

Where secret-data.json contains:

{
  "username": "your-username",
  "token": "your-token"
}

List Secrets

Lists secrets for an organization.

simplismart secrets list [options]

Option	Description
`--org-id UUID`	Organization UUID (required)

Example:

simplismart secrets list --org-id "$ORG_ID"

Expected output

{
  "data": [
    {
      "uuid": "<SECRET_ID>",
      "created_at": "2024-09-12T13:01:55.465292Z",
      "updated_at": "2024-09-12T13:01:55.465316Z",
      "name": "<SECRET_NAME>",
      "secret_type": "gcp",
      "is_simplismart_managed": false,
      "is_system_generated": false,
      "reference_count": 0,
      "org": "<ORG_ID>"
    }
  ]
}

Get Secret

Gets details of a specific secret.

simplismart secrets get [options]

Option	Description
`--secret-id UUID`	Secret UUID (required)

Example:

simplismart secrets get --secret-id <SECRET_ID>

Expected output Returns a single secret object (e.g. uuid, name, secret_type, created_at, updated_at, org). Secret values are never returned.

JSON File Input

Many CLI commands accept JSON input via file path using the @ prefix:

# Pass JSON directly
simplismart deployments create --autoscale-config '{"targets": [{"metric": "gpu", "target": 80}]}'

# Or pass a file path
simplismart deployments create --autoscale-config @autoscale.json

Error Handling

CLI errors are returned as JSON:

{
  "error": "Deployment is already in stopped state",
  "status": 400
}

Quick Reference

Task	Command
List model repos	`simplismart model-repos list`
Create model repo (container)	`simplismart model-repos create-container --name <name> --source-type docker_hub --runtime-gpus 1 --source-secret <SECRET_ID> --registry-path <path> --docker-tag <tag>`
Create model repo (private compile)	`simplismart model-repos create-private-compile --name <name> --avatar-url <url> --source-type huggingface --source-url <path> --model-class <class> --accelerator-type <type> --model-config @model_config.json --optimisation-config @optimisation_config.json --pipeline-config @pipeline_config.json`
List deployments	`simplismart deployments list`
Create deployment	`simplismart deployments create --model-repo <ID> --org $ORG_ID --gpu-id nvidia-h100 --name <name> --min-pod-replicas 1 --max-pod-replicas 2 --autoscale-config @config.json`
Stop deployment	`simplismart deployments stop --deployment-id <ID>`
Start deployment	`simplismart deployments start --deployment-id <ID>`
Delete deployment	`simplismart deployments delete --deployment-id <ID>`
Create secret	`simplismart secrets create --org-id $ORG_ID --name <name> --secret-type docker_hub --data @data.json`
List secrets	`simplismart secrets list --org-id $ORG_ID`

Python

​Installation

​Global Options

​Model Repos Commands

​List Model Repos

​Status Options

​Get Model Repo

​Get Model Profiles

​Bring Your Own Container Model Repo

​Create Private Compile Model Repo

​Delete Model Repo

​Deployments Commands

​List Deployments

​Status Options

​Create Deployment

​Get Deployment

​Update Deployment

​Stop Deployment

​Start Deployment

​Scale Deployment

​Delete Deployment

​Secrets Commands

​Create Secret

​List Secrets

​Get Secret

​JSON File Input

​Error Handling

​Quick Reference

Installation

Global Options

Model Repos Commands

List Model Repos

Status Options

Get Model Repo

Get Model Profiles

Bring Your Own Container Model Repo

Create Private Compile Model Repo

Delete Model Repo

Deployments Commands

List Deployments

Status Options

Create Deployment

Get Deployment

Update Deployment

Stop Deployment

Start Deployment

Scale Deployment

Delete Deployment

Secrets Commands

Create Secret

List Secrets

Get Secret

JSON File Input

Error Handling

Quick Reference