Authentication

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:

Terminal

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:

Terminal

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:

Terminal

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:

Terminal

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 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

  Terminal

  utila auth whoami

  💡

  Want more information about the user? Try using flags, such as --full flag.

• Test the authentication

  Terminal

  utila auth test

  💡

  Want more information about the authentication process? Try using the --verbose flag.