Authentication

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

ℹ️
Be sure to use Utila CLI of version >1.5.0 for the new authentication commands and configuration.

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 [email protected] \
  --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 [email protected] \
  --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="[email protected]"
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="[email protected]"
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 stronger 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.