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

The Chalk CLI supports a number of flags for every command.

Get help for any command in CLI with chalk help [command].

Every command also accepts the -h or --help flag to see help for that command.

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

Configure AI assistant prompts with Chalk-specific context for your preferred AI coding assistant.

This command creates a configuration file tailored to your AI provider that includes:

• Comprehensive Chalk feature engineering best practices - Learn the Chalk way of building features
• Code patterns and examples - Feature classes, resolvers, and expressions with real examples
• DataFrame operations - Windowed aggregations, filtering, and projections
• SQL resolver patterns - Data source integration and optimization techniques
• Performance optimization - Expression compilation to C++ for low-latency execution
• Deployment workflows - Branch deployments, testing strategies, and CI/CD patterns
• LLM integration patterns - Prompt engineering and model integration

Why Use Agent Prompts?

These prompts are carefully crafted and continuously evaluated to ensure AI assistants provide accurate, idiomatic Chalk code that follows best practices. The prompts help AI assistants understand Chalk's unique approach to feature engineering:

• Python-based feature definitions without DSLs
• Expression compilation to C++ for low-latency execution
• Point-in-time correctness for batch queries
• Unified feature and prompt engineering

Supported Providers

• cursor - Creates AGENTS.md for Cursor IDE
• claude - Creates CLAUDE.md for Claude AI
• copilot - Creates .github/copilot-instructions.md for GitHub Copilot
• augment - Creates .augment/rules/chalk-guidelines.md for Augment

All providers receive the same comprehensive Chalk context, ensuring consistent quality assistance regardless of which AI tool you use.

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 migrate-type command to migrate a feature to a new type.

This increments the internal feature version number of a feature—data is not deleted but it will no longer be queryable. This operation is not reversible.

Use the drop-version command to drop all version data for a given set of features.

This command is irreversible, and will drop all version data for the given features. If you no longer want to have versions for a feature, you can drop all previous version data to simplify future deployments.

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 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 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 list-inputs command to view the availabile input file names for your run.

Provide a prefix to filter the input files names by.

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 list-results command to view the availabile result file names from past benchmark runs.

Provide a prefix to filter the result file names by.

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

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.

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.

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.

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

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

List all audit logs for your environment.

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.

This will show detailed information about the container including its phase, image, tags, 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 status, image, phase, and other details.

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 integration list command to view the integrations that are available in this environment.

Integrations can be deleted with chalk integration delete.

Use the 'chalk integration get' command to retrieve a specific integration by name or ID.

You can either specify the integration name/ID with the '--name' flag or select from a list.

Use the chalk integration insert command to create a new integration.

This command allows you to create integrations for various data sources like PostgreSQL, Snowflake, BigQuery, etc. You'll be prompted to provide the necessary environment variables for the integration type you select.

Interactive Mode (recommended)

If no arguments are provided, chalk integration insert will enter interactive mode, which will prompt you for the integration name, type, and required environment variables.

chalk integration insert

With Flags

You can also provide the integration name and kind as flags:

chalk integration insert --name my-postgres --kind postgresql

Available integration kinds:

• athena
• aws
• bigquery
• clickhouse
• cohere
• databricks
• dynamodb
• gcp
• kafka
• kinesis
• mysql
• openai
• postgresql
• pubsub
• redshift
• snowflake
• spanner
• trino

Use the chalk integration delete command to delete an integration.

You can either specify the integration name or ID with the --name flag, select an integration from a list, or specify the integration names/IDs as arguments.

Use the 'chalk webhook list' command to view all webhooks configured in the current environment.

Webhooks can be created with 'chalk webhook create', updated with 'chalk webhook update', and deleted with 'chalk webhook delete'.

Use the 'chalk webhook create' command to create a new webhook that subscribes to Chalk events.

You must provide:

• name: A descriptive name for the webhook
• url: The endpoint URL where events will be sent
• subscriptions: Event types to subscribe to (e.g., query.run, resolver.run)

Optional:

• secret: A secret string for webhook signature verification
• headers: Custom HTTP headers as a JSON object

Use the 'chalk webhook update' command to update an existing webhook.

You must provide the webhook ID, or select from a list if not provided.

All other fields are optional and will only be updated if provided:

• name: New name for the webhook
• url: New endpoint URL
• subscriptions: New event types to subscribe to
• secret: New secret for signature verification
• headers: New custom HTTP headers as a JSON object

Use the 'chalk webhook delete' command to delete a webhook.

You can specify the webhook ID with the '--id' flag, or select from a list if not provided.

Use the chalk secret list command to view the secrets that are available in this environment.

Secrets can be deleted with chalk secret delete.

Use the 'chalk secret get' command to retrieve a specific secret by name.

You can either specify the secret name with the '--name' flag or select from a list.

Use the chalk secret set command to upsert secrets. This command can be used to set one or more secrets at once.

Interactive Mode (recommended)

If no arguments are provided, chalk secret set will enter interactive mode, which will prompt you for the secret name and value. You can also provide only the secret name as an argument, and the CLI will prompt you for the value.

chalk secret set

stdin (recommended)

Using stdin is helpful for setting secrets whose value is the contents of a file:

cat key.pem | chalk secrets set TLS_CERT

You can also use stdin to set the value of a secret to the output of a command or script:

base64 -i chalk.p12 | chalk secrets set PKCS12_CERT

Key-Value Pairs

You can also provide key-value pairs as arguments to chalk secret set.

chalk secrets set HOSTNAME=73.62.143.151
chalk secrets set API_KEY=0x9Xz4#3 PORT=1234

Note that using key-value pairs will cause the secret value to be stored in your shell history. To avoid this, use interactive mode, stdin, or the web dashboard. Or, follow the instructions below to exclude chalk secrets set commands from being stored in your shell history.

Exclude from Shell History

Bash and ZSH will ignore chalk secrets set commands in your shell history if you set the HISTIGNORE or HISTORY_IGNORE environment variables, respectively.

For Bash, add the following to your ~/.bashrc file:

export HISTIGNORE='*chalk secrets set*'

For ZSH, add the following to your ~/.zshrc file:

HISTORY_IGNORE="(chalk secrets set*)"

Use the chalk secret delete command to delete a secret.

You can either specify the secret name with the --name flag, select a secret from a list, or specify the secret names as arguments.

Use this command to get a list of tags and their traffic weights.

Use this command to set the traffic weights and mirror weights for tags. Traffic weights must sum to 100.

Use this command to promote the lowest weighted blue or green tag to 100% traffic serving.

Use this command to set mirror traffic weights for tags. This is useful for testing new features by mirroring a percentage of traffic without affecting main traffic routing.

Use this command to suspend traffic for a specific deployment tag. This sets the traffic weight to nil, which is different from setting it to 0.

Use the flare command to send your code to a partner at Chalk for assistance.

Use the flare list command to list your flares.

Use the chalk flare download command to download a flare by its ID and extract it to a directory. If no ID is provided, an interactive table will be shown for selection.

Submit feedback to the Chalk team.

Use the 'export' command to retrieve and export Chalk usage data based on specified criteria.

The 'export' command allows you to fetch usage data from Chalk and save it as a CSV file for external analysis. You can group the data by 'cluster' or 'instance' and specify the reporting period as either 'daily' or 'monthly'. Additionally, you can set custom date ranges to filter the exported data based on start and end dates.

Open the Chalk dashboard in your web browser.

The chalk doctor command will remove all cached JWTs, leading to new credentials exchange for the next new request. This can be helpful if your ~/.config/chalk.yml file changed or has been corrupted.

Update the Chalk CLI tool. You can always switch back to your old build, stored in ~/.chalk/bin/.

Use the files command to see which of your files will be uploaded to Chalk.

Chalk respects .chalkignore and .gitignore files and only uploads files that don't match patterns in those files.