The Utila CLI uses a state system to securely store persistent data required for operations like transaction signing. This includes device private keys, key shares, and other sensitive information that must be preserved between CLI sessions.

State Architecture

The state system consists of two main components that work together to provide secure, flexible storage:

Storage Location

The state location determines where your state data is stored. The CLI supports multiple storage locations:

Local filesystem (default): Stores state on your local machine
Google Cloud Storage (GCS): Stores state in a GCS bucket
Amazon S3: Stores state in an S3 bucket

For production use cases, especially when running the CLI on multiple machines or in automated environments, cloud storage is recommended.

State Encryption Provider

The state encryption provider determines how your state data is encrypted. The CLI supports multiple encryption options:

Passphrase: Password-based encryption using Argon2id
GCP KMS: Encryption using GCP Key Management Service
AWS KMS: Encryption using AWS Key Management Service

For production environments, it is strongly recommended to use a KMS-based encryption provider for enhanced security.

State File Organization

State data follows a hierarchical structure for easy management:

state/
└── vaults/
    └── {vault-id}/
        └── devices/
            └── {device-id}/
                ├── private_key.pem
                └── key_shares/
                    └── {key-share-id}/
                        └── key_share.json

Each file in the state is encrypted independently, and encryption metadata is stored alongside the encrypted data.

Configuration

Configure your state system by configuring state location and state encryption provider.

State Location

Methods to configure (listed by precedence):

Command-line flag: --state-location
Environment variable: UTILA_STATE_LOCATION
Config command: utila config set state-location

Supported values:

File paths: ~/.utila/state, /var/lib/utila/state, file:///var/lib/utila/state
Cloud storage: s3://my-utila-state-bucket, gs://my-utila-state-bucket

Default: ~/.utila/state (or ~/.config/utila if existing state is found there)

Encryption Provider

Methods to configure (listed by precedence):

Command-line flag: --state-encryption-provider
Environment variable: UTILA_STATE_ENCRYPTION_PROVIDER
Config command: utila config set state-encryption-provider

Supported values:

AWS KMS: awskms://arn:aws:kms:region:account:key/key-id
GCP KMS: gcpkms://projects/project/locations/location/keyRings/ring/cryptoKeys/key
Passphrase: passphrase (password-based encryption)
- For passphrase encryption provider, the passphrase must be supplied, either by inputing it when prompted, or by specifying it using the UTILA_STATE_ENCRYPTION_PASSPHRASEenvironment variable.

Available Commands

The CLI provides several commands to manage your state:

Command	Description
`state info`	Display current state location and encryption provider
`state list`	Show all state files with encryption details
`state move`	Migrate state data between different locations
`state encrypt`	Re-encrypt existing state with a different provider

Use utila [command] --help for detailed options and examples.

Security Best Practices

✅ Do This

Use encryption in all environments, especially production
Choose KMS providers for production workloads (better key management and audit trails)
Use cloud storage for multi-machine setups and automated workflows
Backup your state regularly, particularly before migrations or major changes
Implement proper IAM policies to restrict access to state storage locations
Test your backup and recovery procedures periodically

⚠️ Avoid This

Never commit state files containing private keys to version control systems
Don't use weak passphrases if using passphrase-based encryption
Avoid storing state in publicly accessible cloud storage buckets
Don't share state files between different environments without proper security review

Common Scenarios

Local Development:

# Use default local storage with passphrase
utila config set state-encryption-provider passphrase

Production with Cloud Storage:

# Configure S3 storage with AWS KMS
utila config set state-location s3://company-utila-state
utila config set state-encryption-provider awskms://arn:aws:kms:us-east-1:123456789:key/abcd-1234

Migration Example:

# Move from local to cloud storage
utila state move s3://backup-bucket