Metadata-Version: 2.4
Name: certora-cloud
Version: 0.1.0
Summary: Command-line interface for Certora Cloud services.
Author-email: Certora <support@certora.com>
License-Expression: GPL-3.0-only
License-File: LICENSE
Requires-Python: <3.15,>=3.12
Requires-Dist: aiofile>=3.9.0
Requires-Dist: aiolimiter>=1.2.1
Requires-Dist: keyring>=25.0.0
Requires-Dist: niquests>=3.15.2
Requires-Dist: orjson>=3.11.4
Requires-Dist: platformdirs>=4.3.8
Requires-Dist: pydantic-settings>=2.12.0
Requires-Dist: rich-click>=1.8.9
Requires-Dist: structlog>=25.5.0
Requires-Dist: uvloop>=0.22.1
Description-Content-Type: text/markdown

# 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`):

```bash
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:

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

or using `uvx`:

```console
$ 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:

```console
$ 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:

```bash
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:

```console
# 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": "jane@example.com"
}
```

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

```bash
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:

```bash
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](#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:

```python
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](https://github.com/Certora/certora-cloud-cli-pub/issues).

## 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](./packages/certora_login/README.md).

## Development Setup

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

```bash
direnv allow
```

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

```bash
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:

```bash
make check
```

## Contributing

Bug reports, feature requests, and pull requests are welcome. Please
[open an issue](https://github.com/Certora/certora-cloud-cli-pub/issues) to discuss
significant changes before submitting a PR. All checks (`make check`) must pass.

## License

Licensed under [GPL-3.0-only](LICENSE).

[keyring]: https://github.com/jaraco/keyring
[ruff]: https://github.com/astral-sh/ruff
[nix]: https://nixos.org/
[direnv]: https://github.com/direnv/direnv
[mypy]: https://github.com/python/mypy
[uv]: https://docs.astral.sh/uv/
[pytest]: https://docs.pytest.org/en/stable/
[certora-login]: ./packages/certora_login/README.md
[pipx]: https://github.com/pypa/pipx
