Chalk CLI Reference

Installing Chalk is easy! On Linux and Mac, run the command below to install the latest version of Chalk.

$ curl -s -L https://api.chalk.ai/install.sh | sh

On Windows, download the latest version of the executable from one of the following links:

https://storage.googleapis.com/cli-go.chalk-prod.chalk.ai/latest/chalk-windows-amd64

https://storage.googleapis.com/cli-go.chalk-prod.chalk.ai/latest/chalk-windows-386

Subsequent updates for Mac, Linux, and Windows can be installed using chalk update. After installing, you may need to restart your terminal, or source your shell's rc file (e.g. ~/.bashrc, ~/.zshrc, etc.)

Chalk is a feature platform for real-time machine learning. Use the CLI to deploy feature pipelines, run queries, and manage your Chalk environment.

Connect the CLI to your Chalk account by logging in to persist your client ID and secret locally.

The Chalk CLI runs commands using a global configuration or project-specific configurations. To configure the CLI globally, run:

$ chalk login

You'll be redirected to the dashboard to confirm that you want to give the CLI access to your account.

All configurations are stored in ~/.config/chalk.yml but you can use the XDG_CONFIG_HOME environment variable to override this location.

Use the environment command to view and edit the current environment.

In Chalk, each team has many projects, and each project has many environments. Within an environment, you may define different data sources and different resolvers.

Use the config command to view information about the authorization configuration that the CLI is using to make requests.

When you connect the CLI to your Chalk account by logging in with chalk login, Chalk stores your client ID and secret in ~/.config.yml (unless overridden by the XDG_CONFIG_HOME environment variable).

The config will change according to the active environment (determined by chalk environment and active project (determined by chalk project.

Use the init command to set up a new Chalk project. This command creates two files for you: chalk.yaml and .chalkignore. The first file, chalk.yaml, contains configuration information about your project. The second file, .chalkignore, tells the CLI which files to ignore when deploying to your Chalk environment. You can edit this file and use it just like a .gitignore file.

To configure AI assistant prompts, use chalk init agent-prompt [provider].

Use the project command to view and edit the current project.

In Chalk, each team has many projects, and each project has many environments. A project is defined by a folder with a chalk.yml or chalk.yaml file. The contents within that folder define the features and resolvers of the project. That code is deployed once per environment.

The project configuration file allows you to view and modify:

• Python packages
• Python runtime
• Dockerfile
• Validation settings

Your current working directory (or any parent directory) must contain a chalk.yml or chalk.yaml file.

Use the infra command to manage and update various infrastucture elements of your chalk environment.

The infrastructure under management will change according to the active environment (determined by chalk environment and active project (determined by chalk project.

Use the apply command to deploy your feature pipelines.

Chalk projects have a configuration file in the root of the project named chalk.yml or chalk.yaml. Typically, chalk apply is run from the project root, but it can also be run from any child directory of the project.

The deploy is composed of three steps:

• Local validation: The Chalk CLI uses chalkpy to check for errors in any Chalk resolvers (for example, resolvers that take incompatible inputs and outputs).
• Remote validation: Once local validation passes, Chalk sends the features and resolvers to the server to validate against the deployment.
• Confirmation: Unless --force is specified, you'll see a diff of the features, and asked to confirm before deployment.
• Code upload: The Chalk CLI bundles the code in the project root and sends it to Chalk's servers. Chalk does not upload files matched in your .gitignore or .chalkignore.

Branch deploys

By default, the chalk apply command deploys your features and resolvers to a production serving environment. These deployments roll out gradually over the course of ~1 minute to eliminate downtime.

However, you may wish to iterate more quickly on your feature pipelines. For development, you can use the --branch flag to deploy to a named and ephemeral environment. Branch deployments are optimized for iterating on your feature and resolver definitions and deploy in ~5 seconds.

Once you've deployed to a branch, you can query new features and resolvers in the branch:

> chalk apply --branch feat1
> chalk query --in user.name --out user --branch feat1

Branch deployments also allow you to create or modify features and resolvers from a Jupyter notebook, in real time. You can also use the --reset flag to deploy a clean version of the working directory to a branch, resetting any changes that may have been made from a notebook.

> chalk apply --branch feat1 --reset

File watches

We can make the iteration loop even tighter by adding the --watch flag to the chalk apply --branch command. This will watch for changes to your feature and resolver definitions and deploy them to the branch automatically.

> chalk apply --branch --watch

Use the query command to quickly test your features pipelines.

Chalk supports several API clients for production use. But in development, it is convenient to quickly pull feature values without using an API client or writing code. The chalk query command allows you to pull features and test deployments.

You can even request entire feature classes by asking for the feature namespace. For example,

$ chalk query --in user.id=4 --out user

will return all of the features on user. It will not, however, return all the features of all the has-one relationships of user.

If you do want to return has-one features, you can specify them in the query:

$ chalk query --in user.id=4 \
			 --out user \
			 --out user.card

In the above example, the Chalk CLI will return all the scalar features of user and of user.card.

If you want to query for features from multiple namespaces, you can use a . to indicate an absolute rather than a relative path. By default we will assume that input and output names are relative to the first namespace that we observe in a query, but you can specify different root namespaces:

$ chalk query --in user.id=4 \
              --in .organization.id=5 \
			  --out user.name \
			  --out .organization.name

The "Hit?" column that the command line displays indicates whether the feature was pulled from the online store or not. If it was pulled from the online store, it will be marked with a checkmark (✓).

The link printed out in the command output will take you to a page that shows how the query was executed.

Use the lint command to check for errors in your feature pipelines.

The lint command is composed of two steps:

• Local validation: The Chalk CLI uses chalkpy to check for errors in any Chalk resolvers (for example, resolvers that take incompatible inputs and outputs).
• Remote validation: Once local validation passes, Chalk sends the features and resolvers to the server to validate against the deployment.

Use the delete command to remove features for specific primary keys.

This command is irreversible, and will drop all data for the given features and primary keys in the online and offline stores.

You can also drop data by tag, which can be helpful to meet GDPR requirements. For example, if you tag PII features with pii, you can run

$ chalk delete --tags pii --keys=user2342

Use the trigger command to run resolvers from the CLI.

In addition to scheduling resolver executions, Chalk allows you to trigger resolver executions from the CLI. The trigger endpoint, also supported in Chalk's API clients, allows you to build custom integrations with other data orchestration tools like Airflow.

If you trigger a resolver that takes arguments, Chalk will sample the latest value of all temporally-consistent feature values. Then, it will execute the resolver for each of those arguments.

Use the incremental status command to get the current progress state for an incremental resolver.

Specifically, this returns the timestamps used by the resolver to only process recent input data.

• Max Ingested Timestamp: the latest timestamp found in the input data on the resolver's previous run.
• Last Execution Timestamp: the most recent time at which this resolver was run. By default, incremental resolvers rely only on the max ingested timestamp.

Use the incremental drop command to clear the current progress state for an incremental resolver.

Specifically, this erases the timestamps the resolver uses to only ingest recent data. The next time the resolver runs, it will ingest all historical data that is available.

Use the incremental set command to set the current progress state for an incremental resolver.

Specifically, this configures the timestamps used by the resolver to only process recent input data.

• max_ingested_ts represents the latest timestamp found in the input data on the resolver's previous run.
• last_execution_ts represents the most recent time at which this resolver was run.

Both of these values must be given as ISO-8601 timestamps with a time zone specified.

Use the aggregate backfill command to backfill a materialized window aggregation.

Use the chalk jobs list command to list information about jobs in the queue for your environment.

Use the task run command to execute Python scripts or modules in your deployment.

'target' can be a file path (file.py), module name (my_module), or include a specific function (file.py::func, module::func) or class method (file.py::Class::method, module::Class::method).

Cancel a script task by its task ID.

Retrieve information about a script task by its task ID.

Rerun a script task by its task ID. Creates a new task with the same configuration as the original.

Use the 'chalk scheduled-resolver list' command to view all scheduled resolvers in your environment, showing their resolver FQN and cron schedule. Use --json to get the full output as JSON.

Use the 'chalk scheduled-resolver runs list' command to list scheduled resolver runs for your environment.

You can filter by resolver, time range, and limit the number of results. Use --all to fetch all matching runs by paginating through results.

Use the 'chalk scheduled-resolver runs get' command to retrieve detailed information about a specific scheduled resolver run by its ID.

Use the 'chalk scheduled-query list' command to view all scheduled queries in your environment, showing their cron schedule, output features, and incremental configuration. Use --json to get the full output as JSON.

Use the chalk dataset list command to view information about datasets that have been created in this environment.

Use the 'chalk dataset get' command to view detailed information about a specific dataset.

Use the 'chalk dataset rename' command to change the name of an existing dataset.

Use the 'chalk dataset download' command to download files for a specific dataset revision.

Use the 'chalk dataset archive' command to archive a specific dataset revision.

List recent offline query executions with optional filtering

Retrieve detailed information about a specific offline query by its ID

Download the request body for a specific offline query and re-execute it verbatim by submitting to the remote endpoint

Use the topic push command to push an message to one of your configured Kafka topics.

This command can be useful for testing streaming applications.

The value field accepts special template syntax to generate random values. The following template functions are available:

• rand(): Generate a random float between 0 and 1.
• rand(max): Generate a random float between 0 and max.
• rand(min, max): Generate a random float between min and max, inclusive.
• randint(): Generate a random integer between 0 and 1,000,000, inclusive.
• randint(max): Generate a random integer between 0 and max, inclusive.
• randint(min, max): Generate a random integer between min and max, inclusive.
• randstr(length): Generate a random string of length length.
• now(): Generate the current datetime in ISO 8601 format.

For example, we might push a message of the form:

--value '{"ip": "121.32.randint(255).randint(255)"}'

which would generate messages like {"ip": "121.32.43.232"}.

Use the chalk diff command to compare two branches or deployments in your Chalk environment. If no source is provided, the most recent main deployment will be the source. If a branch is provided, the most recent deployment will be used. This command will compare the different deployments using the diff command-line tool.

Use the chalk source command to download the source code of a Chalk deployment. This command will fetch the source code from the Chalk server and extract it to a temporary directory.

Use the chalk branch start command to start the branch server if it isn't already running. Both chalk apply --branch and chalk query --branch will automatically start the branch server if it isn't already running, so it isn't usually necessary to manually start the branch server.

Use the 'chalk shell' command to open an interactive shell session to a Kubernetes pod. This provides a debug terminal similar to 'kubectl exec -it'.

Use the benchmark run command to kick off a run to benchmark queries - this command is in alpha.

Provide the desired input features, output values, qps, and duration. Default QPS and warmup QPS is 1. Default duration and warmup duration is 1m.

Use the benchmark upload command to upload input files for use in benchmarking.

Provide the path to the desired file to upload. Will use the name of the file as the input-file in benchmark run. Please include the file extension in the file path upload. Only supports the following file types currently: parquet, json.

Use the benchmark download command to download result files from benchmarking runs.

Provide the name to the desired file to download. Please include the file extension in the file path upload.

Retrieve a distributed trace from Chalk.

A trace represents the complete execution path of a request through the Chalk system, showing all operations and their timing information.

List distributed traces from Chalk with optional filtering.

You can filter traces by time range, service name, and span name. By default, this command returns traces from the last hour. Use --all-pages to fetch all available results.

Commands for working with individual spans in traces

List recent query executions with optional filtering

Retrieve detailed information about a specific query run by its ID

List meta queries with optional filtering

Retrieve detailed information about a specific meta query by its ID

Retrieve detailed information about a specific query plan by its ID

List adhoc queries with pagination and filtering support

Use the stubgen command to generate Python stubs using your feature types.

This command generates features that can be used with the ChalkClient class in the chalkpy pip package.

This command generates Go structs that mirror the defined features, and create references to the available features. For details on using the resulting generated code, see the Go client.

Java codegen generates classes that mirror the features classes defined in Python and creates Feature objects for each available feature. If that also fails, please use the --package flag to specify the package name explicitly. For details on using the resulting generated code, see the Java client.

Typescript codegen generates TypeScript types that mirror the defined features. It will also generate a type FeaturesType that can be used to parameterize the Chalk TypeScript client in order to provide automatic autocomplete and type checking for queries.

This command will generate Pydantic models that can be used to describe streaming messages and structs from proto files given with --in.

Show the resolvers you have defined and the features they resolve

Get access tokens and manage service tokens.

List all available permissions that can be assigned to service tokens.

User the user command to print the currently logged-in user.

Useful for checking that your CLI can communicate with Chalk.

Print the build, platform, and version information for the Chalk CLI tool.

Print out Chalk's public changelog in an interactive viewer

List Chalk releases from GitHub with their versions and release notes

Use the chalk branch source command to download the source code for a branch.

Use the chalk branch list command to view information about branches that have been deployed in this environment.

Branches can be created with chalk apply --branch.

List all named queries in the active environment.

Use the healthcheck command to view information on the health of Chalk's api server and its services.

The healthcheck will change according to the active environment (determined by chalk environment and active project (determined by chalk project.

Search through Chalk logs using powerful filtering capabilities.

Searchable Fields:

• resolver: Search by exact resolver name
• query_name: Filter by specific query names
• operation_id: Search using internal query IDs
• correlation_id: Find logs by user-provided query IDs
• trace_id: Filter by trace IDs
• pod_name: Search logs from specific pods
• component: Filter by Chalk components (engine, branch, offline-query)
• message: Search through log message content
• resource_group: Filter by Chalk resource groups
• deployment: Search by Chalk deployment ID
• app: Filter by Kubernetes deployment or statefulset
• all_filter: Search across multiple fields simultaneously
• resolver_filter: Find logs by similar resolver names

If the query by which you're filtering has a space or special character, like a ., enclose it in double quotes.

Output metadata for features from the active deployment to a file. If no output flag is specified, the metadata will be written to 'chalk_features_{environment_id}_{deployment_id}.json' in the current directory.

List all features from the active deployment, displayed by their fully qualified name.

Search for features by their fully qualified name using fuzzy matching. If the pattern contains '*' or '?', it is treated as a glob pattern. Otherwise, fuzzy matching is used.

Resolve metadata for specific features by their fully qualified names (FQNs). This command fetches metadata only for the features specified by the --fqns flag.

Use the chalk pods command to display status of Kubernetes pods that support your Chalk deployment.

Use this to show the current configuration of the online store attached to this environment. This includes details about the DynamoDB or Elasticache backend, such as billing mode, capacity, item count, and region.

List all charts for your Chalk project and print their details in JSON format.

Evaluate a metric chart configuration by calling the GetChartSnapshot API. Takes a JSON object with metricConfig, startTime, and endTime fields and returns the chart's time series data.

Fetch the available metrics, filters, group-by dimensions, window functions, and formulas that can be used to submit metrics queries.

Use the metrics export command to push an message to one of your configured Kafka topics.

Query metrics using a Datadog-inspired query language.

Query syntax: function:metric_name{filter:value,...} by {group,...}.rollup(period)

Components: function - Window function: avg, sum, min, max, count, p99, p95, p75, p50, p25, p5 metric - Metric name, e.g. query.latency, resolver.latency, feature.request_count filters - Optional filters in braces: {resolver_name:my_resolver,status:success} group by - Optional grouping: by {resolver_name} rollup - Optional rollup period: .rollup(5m)

List all audit logs for your environment.

List endpoints configured for audit logging, including their request/response types and audited fields.

List recent query errors with optional filtering by operation ID, feature, resolver, or query name

List query errors aggregated by similar error patterns, showing counts and time ranges

List all available catalogs that can be queried via ChalkSQL.

List available schemas and tables that can be queried via ChalkSQL.

Use the 'chalk container run' command to create and run a new container as a Kubernetes pod.

The container will run in your Chalk environment's Kubernetes cluster with the specified image and configuration.

Use the 'chalk container get' command to retrieve the status of a specific container by its ID or name.

This will show detailed information about the container including its status, image, spec, and creation time.

Use the 'chalk container list' command to list all containers in your Chalk environment.

This will show a table of all containers with their ID, name, status, image, and other details.

Use 'chalk notebook create' to provision a new notebook.

The notebook will run in your Chalk environment.

Use 'chalk notebook get' to view the current status of a notebook. Specify either --id or --name.

Use 'chalk notebook list' to view all notebooks in the current environment.

Use 'chalk notebook stop' to stop a running notebook. Specify either --id or --name.

Use 'chalk sandbox create' to provision a new sandbox pod.

The sandbox will run in your Chalk environment's Kubernetes cluster with the specified image.

Use 'chalk sandbox exec' to run a command in a running sandbox.

Stdin is forwarded to the process, and stdout/stderr are printed to the terminal. The exit code of the remote process is used as the exit code of this command.

Pass -it to allocate a PTY and proxy your terminal, similar to 'docker exec -it'.

Use 'chalk sandbox get' to view the current status of a sandbox.

Use 'chalk sandbox list' to view all sandboxes in the current environment.

Use 'chalk sandbox terminate' to stop and remove a sandbox.

Use the 'chalk scaling-group create' command to create a new scaling group as a Kubernetes Deployment with autoscaling.

The scaling group will run in your Chalk environment's Kubernetes cluster with the specified image, port, and scaling configuration. You can configure min and max replicas for autoscaling, and optionally enable scale-to-zero by setting --min-replicas=0. When scale-to-zero is enabled, a holding proxy will automatically be deployed to handle cold starts.

Use the 'chalk scaling-group get' command to retrieve the status of a specific scaling group by its ID or name.

This will show detailed information about the scaling group including its status, image, replicas, and creation time.

Use the 'chalk scaling-group list' command to list all scaling groups in your Chalk environment.

This will show a table of all scaling groups with their ID, name, status, replicas, image, and other details.

Use the 'chalk scaling-group delete' command to delete a scaling group and its Kubernetes resources.

This will remove the Deployment and associated resources from the cluster.

Use the 'chalk clusters list' command to view clusters available in this team.

Clusters define the Kubernetes infrastructure for your Chalk deployments.

Use the 'chalk clusters describe' command to view detailed information about a specific cluster.

Provide the cluster ID as an argument to retrieve its full configuration and metadata.

Use the 'chalk clusters test' command to verify that Chalk can connect to a cluster.

This command tests the connection to an existing cluster by ID and reports success or failure.

Use the chalk kube events list command to list Kubernetes events from your Chalk environment's clusters.

Use the chalk cloud-account list command to view the cloud account credentials that are available in this environment.

Cloud account credentials allow Chalk to access cloud resources like GCP and AWS for deploying infrastructure.

Use the 'chalk cloud-account test' command to test cloud account credentials.

This command verifies that the credentials can successfully authenticate and access the cloud provider. You can test existing credentials by providing the credential ID as an argument, or select one interactively if no ID is provided.

Use the 'chalk cloud storage configs list' command to view storage configurations available in this team.

Storage configurations define the cloud storage buckets used for plan stages, source uploads, and datasets.

Use the 'chalk cloud storage configs get' command to view details of a specific storage configuration.

You can provide the storage configuration ID as an argument, or select one interactively if no ID is provided.

Use the 'chalk cloud storage configs create' command to create a new storage configuration.

Provide a JSON file path containing the configuration, or pass JSON via stdin.

The JSON file should have the following structure: { "name": "my-storage", "designator": "optional-designator", "kind": "aws", "managed": true, "cloud_credential_id": "optional-credential-id", "plan_stages_bucket": "optional-plan-stages-bucket", "source_upload_bucket": "optional-source-upload-bucket", "dataset_bucket": "optional-dataset-bucket" }

Use the 'chalk cloud storage configs delete' command to delete a storage configuration.

You can provide the storage configuration ID as an argument, or select one interactively if no ID is provided.

Get the offline store table name(s) for a feature by its fully qualified name (FQN).

By default, returns the current active table name. Use --include-historical to see all historical table names (one per internal version, which increments when a feature's dtype changes).

Use the chalk offline-store connection list command to view all offline store connections for the current environment, indicating which is active.

Use the chalk offline-store connection get command to get details of a specific offline store connection. If no ID is provided, the active connection for the current environment is returned, or the only connection if there is just one.

Use the chalk offline-store connection create command to create a new offline store connection. Supports Snowflake, BigQuery, and Iceberg (Glue + S3) backends. Running without flags enters interactive mode.

Use the chalk offline-store connection update command to update an existing offline store connection. Only fields present in the file will be updated.

Use the chalk offline-store connection delete command to delete an offline store connection.

Use the chalk offline-store connection test command to test connectivity for an offline store connection. Provide an ID to test an existing connection, or --file to test a config before creating it.

Use the chalk offline-store connection activate command to bind an offline store connection as active for the current environment.

Use the chalk offline-store connection deactivate command to remove the active offline store connection binding for the current environment.

Use the chalk integration list command to view the integrations that are available in this environment.

Integrations can be deleted with chalk integration delete.