Skip to content

Runvoy CLI Documentation

Autogenerated comprehensive guide to all Runvoy CLI commands.

runvoy

Options

      --debug            Enable debugging logs
  -h, --help             help for runvoy
      --timeout string   Timeout for command execution (e.g., 10m, 30s, 1h) (default "10m")
      --verbose          Verbose output

runvoy claim

Claim a user's API key using the given token

Examples

  - runvoy claim 1234567890

runvoy configure

Configure the local environment with your API key and endpoint URL. This creates or updates the configuration file at ~/.runvoy/config.yaml

runvoy health

Health and reconciliation commands

runvoy health reconcile

Trigger a full health reconciliation across managed resources and display a report

Examples

  - runvoy health reconcile

runvoy images

Docker images management commands

runvoy images list

List all registered Docker images

runvoy images register

Register a new Docker image.

NOTICE: The image will be registered with the current user as the owner and there'll be no validation on the Docker image existence in the registry nor the ability for the task executor to pull the image correctly.

Examples

  - runvoy images register alpine:latest
  - runvoy images register ecr-public.us-east-1.amazonaws.com/docker/library/ubuntu:22.04
  - runvoy images register ubuntu:22.04 --set-default

Options

      --cpu string                Optional CPU value (e.g., 256, 1024). Defaults to 256 if not specified
  -h, --help                      help for register
      --memory string             Optional Memory value (e.g., 512, 2048). Defaults to 512 if not specified
      --runtime-platform string   Optional runtime platform (e.g., Linux/ARM64, Linux/X86_64). Defaults to Linux/ARM64 if not specified
      --set-default               Set this image as the default image
      --task-exec-role string     Optional task execution role name for the image
      --task-role string          Optional task role name for the image

runvoy images show

Show detailed information about a Docker image

Examples

  - runvoy images show alpine:latest
  - runvoy images show alpine:latest-a1b2c3d4

runvoy images unregister

Unregister a Docker image

Examples

  - runvoy images unregister alpine:latest

runvoy infra

Commands for applying and managing backend infrastructure.

runvoy infra apply

Apply or update the backend infrastructure.

By default, this command uses the official template from the releases bucket for the current CLI version. You can override this with a custom template URL or a local file path.

Examples

  # Apply using default template and version
  runvoy infra apply --stack-name my-stack

  # Apply a specific version
  runvoy infra apply --stack-name my-stack --version 1.2.3

  # Apply with custom template from S3
  runvoy infra apply --stack-name my-stack --template https://my-bucket.s3.amazonaws.com/template.yaml

  # Apply with local template file
  runvoy infra apply --stack-name my-stack --template ./my-template.yaml

  # Apply with custom parameters
  runvoy infra apply --stack-name my-stack --parameter ProjectName=myproject --parameter LambdaCodeBucket=my-bucket

  # Apply and automatically configure CLI
  runvoy infra apply --stack-name my-stack --configure

  # Apply, configure CLI, and seed admin user
  runvoy infra apply --stack-name my-stack --configure --seed-admin-user admin@example.com

Options

      --configure                Automatically configure CLI with the applied endpoint after successful application
  -h, --help                     help for apply
      --parameter strings        Stack parameter in KEY=VALUE format (can be specified multiple times)
      --provider string          Cloud provider (currently supported: aws) (default "aws")
      --region string            Provider region. Uses provider default if not specified
      --seed-admin-user string   Email address for the admin user to seed into DynamoDB after successful deployment
      --stack-name string        Infrastructure stack name (default "runvoy-backend")
      --template string          Template URL or local file path. If not specified, uses the official template
      --version string           Release version to apply. Defaults to CLI version
      --wait                     Wait for stack operation to complete (default true)

runvoy infra destroy

Destroy the backend infrastructure stack.

This command will delete all resources created by the apply command, including the CloudFormation stack and all associated AWS resources.

Examples

  # Destroy infrastructure stack
  runvoy infra destroy --stack-name my-stack

  # Destroy without waiting for completion
  runvoy infra destroy --stack-name my-stack --wait=false

Options

  -h, --help                help for destroy
      --provider string     Cloud provider (currently supported: aws) (default "aws")
      --region string       Provider region. Uses provider default if not specified
      --stack-name string   Infrastructure stack name (default "runvoy-backend")
      --wait                Wait for stack deletion to complete (default true)

runvoy kill

Kill a running command execution

runvoy list

List command executions present in the runvoy backend with optional filtering. Show last 10 executions and all statuses by default. Use --limit and --status flags to customize the output.

Examples

  # Show last 10 executions
  - runvoy list

  # Show last 100 executions
  - runvoy list --limit 100

  # Show last 20 executions and filter by RUNNING and SUCCEEDED statuses
  - runvoy list --limit 20 --status RUNNING,SUCCEEDED

Options

  -h, --help            help for list
      --limit int       maximum number of executions to return (default: 10, use 0 for all) (default 10)
      --status string   comma-separated list of execution statuses to filter by (e.g., RUNNING,TERMINATING)

runvoy logs

Get logs for an execution

runvoy playbook

Manage and execute reusable command execution configurations defined in YAML files

runvoy playbook list

List all playbooks found in the .runvoy directory

runvoy playbook run

Execute a playbook with optional flag overrides

Examples

  - runvoy playbook run terraform-plan

Options

  -p, --git-path string   Override git path
  -r, --git-ref string    Override git reference
  -g, --git-repo string   Override git repository URL
  -h, --help              help for run
  -i, --image string      Override image
      --secret strings    Add additional secrets (merge with playbook secrets)

runvoy playbook show

Display the full content of a playbook

Examples

  - runvoy playbook show terraform-plan

runvoy run

Run a command in a remote environment with optional Git repository cloning.

User environment variables prefixed with RUNVOY_USER_ are saved to .env file in the command working directory.

Examples

  - runvoy run echo hello world
  - runvoy run terraform plan

  # With private Git repository cloning
  - runvoy run --secret github-token \
               --git-repo https://github.com/mycompany/myproject.git \
               npm run test

  # With public Git repository cloning and a specific Git reference and path
  - runvoy run --git-repo https://github.com/ansible/ansible-examples.git \
               --git-ref main \
               --git-path ansible-examples/playbooks/hello_world \
               ansible-playbook site.yml

  # With user environment variables
  - RUNVOY_USER_MY_VAR=1234567890 runvoy run cat .env # Outputs => MY_VAR=1234567890

Options

  -p, --git-path string   Git path
  -r, --git-ref string    Git reference
  -g, --git-repo string   Git repository URL
  -h, --help              help for run
  -i, --image string      Image to use
      --secret strings    Secret name to inject (repeatable)

runvoy secrets

Secrets management commands

runvoy secrets create

Create a new secret with the given name, key name (environment variable name), and value

Examples

  - runvoy secrets create github-token GITHUB_TOKEN "ghp_xxxxx"
  - runvoy secrets create db-password DB_PASSWORD "secret123" --description "Database password"

Options

      --description string   Description for the secret
  -h, --help                 help for create

runvoy secrets delete

Delete a secret by its name

Examples

  - runvoy secrets delete github-token

runvoy secrets get

Retrieve a secret by its name, including its value

Examples

  - runvoy secrets get github-token

runvoy secrets list

List all secrets in the system with their basic information

Examples

  - runvoy secrets list

runvoy secrets update

Update a secret's metadata (description, key_name) and/or value

Examples

  - runvoy secrets update github-token --key-name GITHUB_API_TOKEN --value "new-token"
  - runvoy secrets update db-password --description "Updated database password"

Options

      --description string   Description for the secret
  -h, --help                 help for update
      --key-name string      Environment variable name (e.g., GITHUB_TOKEN)
      --value string         Secret value to update

runvoy status

Get the status of a command execution

runvoy trace

Get backend logs and related resources for a given request ID

Examples

  runvoy trace c2584f31-f753-4a07-9556-ed79dc36a10b

runvoy users

User management commands

runvoy users create

Create a new user with the given email and role

Examples

  - runvoy users create alice@example.com --role viewer
  - runvoy users create bob@another-example.com --role developer

Options

  -h, --help          help for create
      --role string   User role (admin, operator, developer, or viewer)

runvoy users list

List all users in the system with their basic information

Examples

  - runvoy users list

runvoy users revoke

Revoke a user's API key

runvoy version

Show the version of the CLI