Vals AI CLI and SDK Tool

Install

pip install valsai

Overview

This Python package contains two items - a CLI tool to use Vals from the command line, and an SDK to use Vals from Python code.

All code is contained within vals/, separated by CLI and SDK. Note that many of the CLI functions are just thin wrappers around the SDK.

Examples

We've provided a set of examples in examples/. They are organized as follows:

suites/ - These are example JSON files, of the sort that you may use for vals suite create <example.json>.
scripts/ - These are example Python scripts that leverage the sdk.

Authentication

Make an account at platform.vals.ai and confirm your email.

Then, go to platform.vals.ai/project/default-project/settings/api-keys and create an API key. If using a different project, navigate to that project's settings instead.

If you are using the command line, you should set the following:

export VALS_API_KEY=<YOUR API KEY>

If you're using the EU instance of vals, you should also set export VALS_REGION=europe. Include these in your .zshrc / .bashrc to make them permanent.

See the documentation for passing in your API key directly via Python code for SDK usage.

CLI Usage

The CLI is run as follows:

$ vals

Use the --help flag at the top and subcommand level for guidance.

Commands must be run from the pip environment the cli was installed in. Commands are split up into subcommands. Currently there are three main subcommands:

vals suite --help: relating to creating / updating tests and suites
vals run --help: relating to creating and querying runs and run results
vals project --help: relating to listing and managing projects

Full documentation of the CLI usage can be found in our documentation at docs.vals.ai/cli/cli

SDK Usage

All of the functionality that is in the CLI can also be accessed via Python functions, as well as features only available in the SDK.

See usage documentation in our docs: docs.vals.ai/sdk

Development

The SDK uses uv for dependency management. A Makefile is provided for common tasks. See the root README for full environment setup instructions.

Local Installation

make install

To install the SDK in editable mode in another project (apply local changes without reinstalling):

uv pip install -e /path/to/platform/sdk

Makefile Commands

make install        Install dependencies for development
make test           Run tests
make style          Lint & format (ruff)
make typecheck      Run basedpyright
make codegen        Generate GraphQL client

Running Codegen

Add additional .graphql files to vals/graphql, then run the following command:

make codegen

ariadne-codegen --config codegen-config.toml

NOTE: This will overwrite anything in the vals/graphql_client directory.

Metadata

Release files for valsai 0.3.12

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for valsai 0.3.12
File	Size	Uploaded
valsai-0.3.12.tar.gz	366.8 kB	Oct 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for valsai 0.3.12
File	Interpreter	ABI	Platform	Reset
valsai-0.3.12-py3-none-any.whl 113.8 kB Oct 14, 2026	Python 3	none	any	Details

Total release size: 480.7 kB

Release files / valsai-0.3.12.tar.gz

Download URL	valsai-0.3.12.tar.gz
Size	366.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`02f9c3055941525b7c83fe623e23b5cf2521b2be3d2f9a68c0ccf9a79f56f099`
BLAKE2b-256 checksum How to use checksums	`664afb6630e19b3033791cf6d04cabcdbd13e522d1958a988af7dd1d099cd4e7`
Upload date	Oct 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/vals-ai/platform
Publishing commit: github.com/vals-ai/platform/tree/4516c58886c627f1e4c16468321093ace3f9e68a

Workflow

Publishing configuration: github.com/vals-ai/platform/blob/4516c58886c627f1e4c16468321093ace3f9e68a/.github/workflows/sdk-publish.yml
Publishing logs: github.com/vals-ai/platform/actions/runs/38490212463/attempts/1

Artifact

Subject: valsai-0.3.12.tar.gz
SHA-256 checksum: 02f9c3055941525b7c83fe623e23b5cf2521b2be3d2f9a68c0ccf9a79f56f099 Verifying attestations

Release files / valsai-0.3.12-py3-none-any.whl

Download URL	valsai-0.3.12-py3-none-any.whl
Size	113.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`718856b13f6fdfc619f86e1b7aebd6f345d4989c52214748da5333ce05756b1b`
BLAKE2b-256 checksum How to use checksums	`c79b00949294b3b9a6e10018db7cbc2c64243c16a39649a07afc465ddbc458dc`
Upload date	Oct 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/vals-ai/platform
Publishing commit: github.com/vals-ai/platform/tree/4516c58886c627f1e4c16468321093ace3f9e68a

Workflow

Publishing configuration: github.com/vals-ai/platform/blob/4516c58886c627f1e4c16468321093ace3f9e68a/.github/workflows/sdk-publish.yml
Publishing logs: github.com/vals-ai/platform/actions/runs/38490212463/attempts/1

Artifact

Subject: valsai-0.3.12-py3-none-any.whl
SHA-256 checksum: 718856b13f6fdfc619f86e1b7aebd6f345d4989c52214748da5333ce05756b1b Verifying attestations