The Utila CLI provides a flexible authentication system that allows to authenticate using service accounts.

ℹ️
Use Utila CLI version 1.5.0 or later to access the latest authentication commands and configuration options.

Prerequisites

The CLI uses service accounts for authentication. If you don't have a service account, please refer to the Creating a Service Account guide to create one.

To authenticate the CLI with a service account, you'll need to provide the CLI with its credentials, so make sure you have:

The service account email
The service account private key, either:
- A private key file — a file containing the service account’s private key, or
- A KMS key resource name — if the private key is securely stored in a Key Management Service (KMS).

Configuration

The CLI supports two ways of providing the required credentials:

1. Configuration Command

Provide the credentials using the utila auth add-service-account-credentialscommand.

📘
Example
Providing a path to the service account private key to save it in the local configuration:
utila auth add-service-account-credentials \
  --email my-service-account@vault-a1b2c3d4.utilaserviceaccount.io \
  --private-key-path ~/keys/my-service-account-key.pem

📘
Example
Providing the resource name of a service account key which resides in a KMS:
utila auth add-service-account-credentials \
  --email my-service-account@vault-a1b2c3d4.utilaserviceaccount.io \
  --kms-key-url awskms:///arn:aws:kms:us-east-1:1234567890:key/12345678-1234-1234-1234-123456789012

2. Environment Variables

Provide the credentials using environment variables:

UTILA_ACCOUNT - The service account email.
Private key, either:
- UTILA_SA_PRIVATE_KEY- The private key (contents of the key file), or
- UTILA_SA_KMS_KEY_URL - The KMS key URL.

📘
Example
Setting the account and the private key contents using environment variables:
export UTILA_ACCOUNT="my-service-account@vault-a1b2c3d4.utilaserviceaccount.io"
export UTILA_SA_PRIVATE_KEY="$(cat ~/keys/my-service-account-key.pem)"

📘
Example
Setting the account and the KMS key using environment variables:
export UTILA_ACCOUNT="my-service-account@vault-a1b2c3d4.utilaserviceaccount.io"
export UTILA_SA_KMS_KEY_URL="awskms:///arn:aws:kms:us-east-1:1234567890:key/12345678-1234-1234-1234-123456789012"

💡
Useful for quick testing, scripts, or CI/CD pipelines.

Best Practices

Prefer KMS keys in production for tighter security.
Use environment variables for temporary sessions or CI/CD pipelines.
NEVER commit keys or credentials to version control.

Troubleshooting

The CLI provides commands to verify and debug your authentication setup:

Print the currently authenticated account
```
utila auth whoami
```
💡
Want more information about the user? Try using flags, such as --full flag.
Test the authentication
```
utila auth test
```
💡
Want more information about the authentication process? Try using the --verbose flag.