signadot-cli

name	signadot-cli
description	Manage Signadot sandboxes, route groups, clusters, resource plugins, secrets, jobs, and smart tests using the signadot CLI. Use when a developer or platform engineer needs to create, update, inspect, or delete Signadot resources.
argument-hint	[resource: sandbox|routegroup|cluster|job|resourceplugin|secret|smart-test]

Signadot CLI

Help the user manage Signadot resources using the signadot CLI. If the user specifies a resource type ($ARGUMENTS), focus on that section. Otherwise, provide guidance based on what they're trying to accomplish.

Core Concepts

• Sandbox: An isolated environment comprising forked workloads, local workloads, or virtual workloads plus ephemeral resources. Each sandbox gets a unique routing key for request routing.
• Route Group: Dynamically groups sandboxes by label criteria and provides shared preview URLs. Useful for combining multiple sandboxes into a single test environment.
• Preview URL: An authenticated URL that routes traffic to a specific sandbox or route group by automatically injecting the routing key.
• Resource Plugin: A reusable template for provisioning ephemeral resources (databases, queues, etc.) within sandboxes.
• Templates: YAML files with @{variable} directives, expanded at apply time with --set variable=value.

Configuration

The main configuration for the CLI is authentication (org and optionally api key) and configuration for signadot local.

The CLI reads $HOME/.signadot/config.yaml by default. Use --config to switch:

signadot --config ~/configs/staging.yaml sandbox list

See authentication below for authentication information and the signadot-local skill for local configuration.

Authentication

# Interactive browser login
signadot auth login

# API key login
signadot auth login --with-api-key <key>

# Check status
signadot auth status

# Logout
signadot auth logout

For CI, use environment variables: SIGNADOT_ORG and SIGNADOT_API_KEY.

Sandbox Management (alias: sb)

Create or Update a Sandbox

Write a YAML spec file and apply it:

# my-sandbox.yaml
name: my-sandbox
spec:
  cluster: my-cluster
  description: Testing new feature
  forks:
  - forkOf:
      kind: Deployment
      namespace: example
      name: my-app
    customizations:
      images:
      - image: example.com/my-app:dev-abcdef
        container: my-app
      env:
      - name: FEATURE_FLAG
        container: my-app
        operation: upsert
        value: "true"
  defaultRouteGroup:
    endpoints:
    - name: my-endpoint
      target: http://my-app.example.svc:8080

signadot sandbox apply -f my-sandbox.yaml

With Templates

# sandbox-template.yaml
name: "@{dev}-feature-x"
spec:
  cluster: "@{cluster}"
  description: "Feature X sandbox for @{dev}"
  forks:
  - forkOf:
      kind: Deployment
      namespace: "@{namespace}"
      name: my-app
    customizations:
      images:
      - image: "example.com/my-app:@{tag}"
        container: my-app

signadot sandbox apply -f sandbox-template.yaml \
  --set dev=jane \
  --set cluster=staging \
  --set namespace=default \
  --set tag=pr-42-abc123

Template Features

• Variables: @{variable} — replaced via --set variable=value
• Embeddings: @{embed: file.txt} — inline file contents
• Encodings: @{var[yaml]} for YAML expansion, @{var[binary]} for binary, @{var[raw]} (default) for string interpolation

List, Get, Delete

# List all sandboxes
signadot sandbox list
signadot sb list -o json

# Get details
signadot sandbox get my-sandbox
signadot sb get my-sandbox -o yaml

# Delete by name
signadot sandbox delete my-sandbox

# Delete by spec file
signadot sandbox delete -f my-sandbox.yaml

Sandbox with Local Mappings

Requires signadot local connect first (see the signadot-local skill).

name: my-local-sandbox
spec:
  cluster: staging
  local:
  - name: local-my-app
    from:
      kind: Deployment
      namespace: hotrod
      name: my-app
    mappings:
    - port: 8080
      toLocal: localhost:3000

Working with Local Sandbox Configuration

After creating a sandbox with local mappings, extract the environment and files the workload needs:

# Get environment variables (can be eval'd or sourced)
signadot sandbox get-env my-local-sandbox

# Get mounted files (ConfigMaps, Secrets)
signadot sandbox get-files my-local-sandbox

Sandbox TTL (Auto-deletion)

spec:
  ttl:
    duration: "2h"        # auto-delete after 2 hours
    offsetFrom: createdAt  # or updatedAt

Route Group Management (alias: rg)

Route groups combine multiple sandboxes via label matching and provide shared endpoints.

# my-routegroup.yaml
name: my-routegroup
spec:
  cluster: my-cluster
  description: "Route group for feature X"
  match:
    any:
    - label:
        key: feature
        value: "feature-x-*"
  endpoints:
  - name: frontend
    target: http://frontend.hotrod.svc:8080

# Apply
signadot routegroup apply -f my-routegroup.yaml

# List
signadot routegroup list
signadot rg list -o json

# Get details
signadot routegroup get my-routegroup

# Delete
signadot routegroup delete my-routegroup

Match Criteria

• Single label: match.label: {key: "k", value: "v"}
• Any (OR): match.any: [{label: {key: "k1", value: "v1"}}, ...]
• All (AND): match.all: [{label: {key: "k1", value: "v1"}}, ...]
• Values support glob patterns: value: "feature-*"

Cluster Management (alias: cl)

# Add a cluster
signadot cluster add --name my-cluster

# List clusters
signadot cluster list

# Manage cluster tokens
signadot cluster token list --cluster my-cluster
signadot cluster token create --cluster my-cluster
signadot cluster token delete --cluster my-cluster <token-id>

# Analyze DevMesh workloads
signadot cluster devmesh analyze --cluster my-cluster

Devbox Management

Devboxes represent developer machines connected via signadot local connect.

# Register a devbox
signadot devbox register --name my-devbox

# List devboxes (own)
signadot devbox list

# List all devboxes in org
signadot devbox list --all

# Delete a devbox
signadot devbox delete <devbox-id>

Resource Plugin Management (alias: rp)

Resource plugins provision ephemeral resources (databases, queues, etc.) for sandboxes.

Plugins are versioned with semver. The name: field carries the wire identity as a single token of the form bareName[@semver] — e.g. my-plugin@1.2.0. A bare name with no @ suffix publishes to the default version (0.0.0).

Every published (name, version) pair is immutable, including 0.0.0 — to roll out changes, bump the version. Re-applying an existing version returns a 409 from the server; the CLI maps that to a tailored message naming the bare recovery path for users who don't yet have an @semver suffix (add an @<semver> suffix to publish a new revision (e.g. my-plugin@0.0.1)).

Sandboxes reference a plugin as plugin: name[@version]; omitting the version (or using @latest) resolves to the highest-semver published version at sandbox-creation time, after which the resolved version is persisted on the sandbox.

get -o yaml round-trips straight back into apply -f — the output's name field is the input form.

# my-plugin.yaml
name: my-plugin@1.2.0
spec: { ... }

# Apply a resource plugin spec (publishes the version from the file)
signadot resourceplugin apply -f my-plugin.yaml

# List plugins (highest-semver version of each). When any plugin has
# multiple versions, a footer hint points at --all-versions.
signadot resourceplugin list

# List every published version of every plugin (one row per name+version)
signadot resourceplugin list --all-versions
signadot resourceplugin list -A

# List every published version of one plugin (highest semver first)
signadot resourceplugin versions my-plugin

# Get details — omit @version for latest
signadot resourceplugin get my-plugin
signadot resourceplugin get my-plugin@1.2.0

# Delete — omit @version for latest; specific versions are deletable if
# no sandbox references that exact version. The bare form removes only
# the latest version; the CLI warns when other versions remain so users
# don't mistake "delete my-plugin" for "delete every version".
signadot resourceplugin delete my-plugin@1.2.0

# Delete-in-use: 400 from the server is enriched client-side with the
# names of the sandboxes still holding the version.

Secrets (alias: secrets)

Org-level encrypted secrets. The plaintext value is write-only — get/list return metadata only (name, description, createdAt, updatedAt) and never expose the value.

# Create — value can come from a literal, a file, or stdin
signadot secret create my-db-password --value 'hunter2'
signadot secret create my-db-password --value-file ./password.txt
echo -n 'hunter2' | signadot secret create my-db-password --value-stdin

# Or from a flat YAML/JSON file with optional --set expansion
signadot secret create -f secret.yaml --set VALUE=hunter2

# Update — value is required (same flag set as create)
signadot secret update my-db-password --value 'newpass'

# Inspect (metadata only)
signadot secret get my-db-password
signadot secret list
signadot secret list -o json

# Delete
signadot secret delete my-db-password
signadot secret delete -f secret.yaml

Secret file shape (no spec: stanza):

name: my-db-password
description: Prod DB password
value: '@{VALUE}'

Binding secrets to plan params

Plan runs pull a secret value into a parameter via --param-secret param-name=secret-name (parallel to --param, repeatable):

signadot plan run my-plan --param-secret db_pass=my-db-password

A given param name must use either --param or --param-secret, not both.

Job Management

Jobs run tests or tasks in the context of a sandbox.

# Submit a job
signadot job submit -f my-job.yaml --set sandbox=my-sandbox

# List jobs
signadot job list
signadot job list --all

# Get job details
signadot job get my-job

# Cancel/delete a job
signadot job delete my-job

Smart Tests (alias: st)

# List smart tests
signadot smart-test list

# Run a smart test
signadot smart-test run <test-name>

# List executions
signadot smart-test execution list

# Get execution details
signadot smart-test execution get <execution-id>

# Cancel execution
signadot smart-test execution cancel <execution-id>

Job Runner Groups (alias: jrg)

signadot jobrunnergroup list
signadot jobrunnergroup get <name>
signadot jobrunnergroup apply -f <file>
signadot jobrunnergroup delete <name>

MCP Server

The CLI can run as an MCP (Model Context Protocol) server for AI-assisted workflows:

signadot mcp

Output Formats

Most commands support -o json or -o yaml for machine-readable output:

signadot sandbox list -o json
signadot routegroup get my-rg -o yaml

Common Patterns

CI/CD: Create sandbox per PR

signadot sandbox apply -f sandbox.yaml \
  --set name="pr-${PR_NUMBER}" \
  --set tag="${COMMIT_SHA}" \
  --set cluster=staging

CI/CD: Clean up on PR close

signadot sandbox delete "pr-${PR_NUMBER}"

Test against a sandbox

# Get the preview URL
signadot sandbox get my-sandbox -o json | jq -r '.endpoints[0].url'

# Or use local proxy for direct access
signadot local proxy --sandbox my-sandbox \
  --map http://backend.staging.svc:8000@localhost:8001

Troubleshooting

• "sandbox not found": Check signadot sandbox list and verify the name
• Sandbox stuck in non-Ready state: Check signadot sandbox get <name> -o yaml for status conditions
• Template errors: Ensure all @{variables} have corresponding --set flags
• Permission errors: Verify signadot auth status shows authenticated