certora-cloud 0.1.0

Command-line interface for Certora Cloud services.

Certora Cloud CLI

Welcome to the Certora Cloud CLI! This command-line interface (CLI) tool allows you to interact with Certora Cloud services, manage your jobs, and perform various operations directly from the command line. It leverages the PKCE login flow provided by the low-level certora-login package and safely stores credentials using keyring.

Installation

The recommended way to install Certora Cloud CLI is via uv (uvx):

uv tool install 'git+https://github.com/Certora/certora-cloud-cli-pub.git'

Please make sure you have uv installed and set up correctly. To fix your PATH environment, you can use the uv tool update-shell command. For more information, please refer to the uv documentation.

Afterwards, you should be able to use the certora-cloud command in your terminal:

$ certora-cloud --version
certora-cloud, version 0.1.2.dev3+g8ccac119a.d19800101

or using uvx:

$ uvx certora-cloud --version
certora-cloud, version 0.1.2.dev3+g8ccac119a.d19800101

[!NOTE] Why uv? Uv is a modern Python tool designed to simplify development environments and dependency management. It makes installing and managing Python packages easy and efficient, helping you maintain correct dependency versions and keep your projects isolated from each other.

As an alternative, you can install this package using pip or pipx directly from GitHub. Since this package depends on the low-level certora-login package (part of this monorepo), install both from this repository.

Shell Completion

To simplify usage, the CLI tool provides shell completion scripts for bash, zsh, and fish shells. You can set it up using the following command:

$ certora-cloud shell-completion

For "zsh", add one of the following to your "~/.zshrc":

# Dynamic completion (executes every time a new shell is started)
eval "$(_CERTORA_CLOUD_COMPLETE=zsh_source certora-cloud)"

# Static completion (has to be regenerated on updates)
_CERTORA_CLOUD_COMPLETE=zsh_source certora-cloud > ~/.certora-cloud-complete.zsh

# Source the file in "~/.zshrc":
. ~/.certora-cloud-complete.zsh

The CLI will try to automatically detect your shell using the SHELL environment variable and provide the necessary setup instructions. If it cannot detect your shell, you can specify it manually using the --shell option.

Upgrading

If you installed the package using uv, you can upgrade it with:

uv tool upgrade certora-cloud

Usage

After installing the package, you can use the certora-cloud command in your terminal. All commands and subcommands are documented with the --help flag.

Some common use cases:

# Login to Certora Cloud
$ certora-cloud login

# Fast parallel file download
$ certora-cloud job download \
  -f inputs -f outputs -f treeView/treeViewsStatus.json \
  1d84e822-5584-4ff4-bdae-3c7d92ad94af stg:97f03df2-3f53-4761-b9b5-19b1f2a83026

# Get links with anonymous key
$ certora-cloud job link --with-anonymous-key 5caa1780-3daa-4bfb-b19e-375e24c08b7d prod:5caa17803daa4bfbb19e375e24c08b7d stg:97f03df2-3f53-4761-b9b5-19b1f2a83026
https://prover.certora.com/output/60724/5caa17803daa4bfbb19e375e24c08b7d/?anonymousKey=my-secret-anonymous-key-1
https://vaas-stg.certora.com/output/1010/97f03df23f534761b9b519b1f2a83026/?anonymousKey=my-secret-anonymous-key-2


# Exporting Certora cookies for curl/wget usage
$ certora-cloud export-cookies --export-type file -o cookies.txt
$ curl -b cookies.txt https://prover.certora.com/who-am-i | jq '{user_name, email}'
{
  "user_name": "jane",
  "email": "[e-mail]"
}

and much more. For a full list of commands, please refer to the help:

certora-cloud --help

Credential Loading Order

Credentials are loaded from the following sources, in order of priority:

1. Environment variables — CERTORA_TOKEN, CERTORA_REFRESH_TOKEN, and CERTORA_USER
2. Credentials file — ~/.certora/credentials.json (or custom path)
3. System keyring — via keyring

This is especially useful for CI/CD pipelines or remote machines where the browser-based PKCE flow is not available:

export CERTORA_TOKEN="your-token"
export CERTORA_REFRESH_TOKEN="your-refresh-token"
export CERTORA_USER="your-user-id"
certora-cloud job download ...

Login Behaviour Environment Variables

When calling certora_login.login() programmatically, its kwargs default to a _NotSet sentinel and fall back to CERTORA_LOGIN_* env vars before the hardcoded defaults:

Variable	Default	Effect
CERTORA_LOGIN_ENV	prod	Target environment (prod, stg, dev)
CERTORA_LOGIN_FORCE_FILE	false	Save to file even if keyring is available
CERTORA_LOGIN_SAVE	true	Persist credentials after login
CERTORA_LOGIN_NO_BROWSER	false	Skip opening the system browser
CERTORA_LOGIN_NO_PKCE	false	Skip the PKCE flow (use stored credentials only)
CERTORA_LOGIN_TIMEOUT	30.0	HTTP timeout in seconds; also sets the PKCE deadline

Booleans are True for "1" or "true", False for "0" or "false" (case-insensitive). Any other value (including unset) uses the default. The certora-cloud CLI always passes kwargs explicitly, so these env vars do not affect CLI usage — only direct calls to login(). See the certora-login README for details.

Limitations

As we're using the PKCE login flow, the CLI currently only supports the localhost flow, which means that the user has to be on the same machine where the CLI is running. For remote machines or CI/CD environments, you can provide credentials via environment variables (see Credential Loading Order) or use the --force-file option to save credentials to a file and copy it to the other machine. Please be very careful when doing this, as the file contains sensitive information!

Usage as a Python Package

This CLI tool is also available as a Python package named certora-cloud. You can import and use it in your Python scripts as follows:

from certora_cloud.api.http_client import get_session

session = get_session()
response = session.get("https://prover.certora.com/who-am-i")
print(response.json())

If you think some functionality would be useful to have as part of the Python package, please open an issue.

Low Level Login Package

The certora-login package provides low-level functions to log in using the PKCE flow and make authenticated requests to Certora Cloud services. In most cases, you should use the CLI tool instead of this package directly. If you do want to use it directly, please refer to the certora-login README.

Development Setup

To set up the development environment, we recommend using nix along with direnv. After cloning the repository, run the following command:

direnv allow

This will set up the environment automatically. Then, install all dependencies using uv:

make install
prek install   # optional: enable the git pre-commit hooks

For development, we use a combination of ruff, mypy, and pytest. You can run all checks using:

make check

Contributing

Bug reports, feature requests, and pull requests are welcome. Please open an issue to discuss significant changes before submitting a PR. All checks (make check) must pass.

License

Licensed under GPL-3.0-only.