# Chalk CLI Reference: Basic Operations
source: https://docs.chalk.ai/cli#basic-operations

Deploy [feature pipelines](https://docs.chalk.ai/docs/resolver-overview), run [queries](https://docs.chalk.ai/docs/query-basics), and manage your Chalk deployment. These are the core commands you'll use daily to interact with Chalk.

## `chalk apply`
source: https://docs.chalk.ai/cli?command=apply

```bash
chalk apply [flags]
```

Use the `apply` command to deploy your feature pipelines.

Chalk projects have a configuration file in the root of the project named [`chalk.yml`](https://docs.chalk.ai/docs/docker) or [`chalk.yaml`](https://docs.chalk.ai/docs/docker). 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`](https://pypi.org/project/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`](https://git-scm.com/docs/gitignore) or `.chalkignore`.

**Branch deploys**

By default, the [`chalk apply`](https://docs.chalk.ai/cli?command=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`](https://docs.chalk.ai/cli?command=chalk#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](https://docs.chalk.ai/docs/branches#develop-in-a-notebook). 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`](https://docs.chalk.ai/cli?command=apply#watch) flag to the [`chalk apply --branch`](https://docs.chalk.ai/cli?command=apply) command. This will watch for changes to your feature and resolver definitions and deploy them to the branch automatically.

```
> chalk apply --branch --watch
```

**Flags**

- `-f, --force <force>` (bool, default `false`)
  If `true`, skip confirmation before creating a new deployment.
- `-a, --await <await>` (bool, default `true`)
  If `true`, wait for the deployment to go live before exiting. Otherwise, exit and print a deployment URL that tracks the deployment progress.
- `-p, --plan <plan>` (bool, default `false`)
  If `true`, the deployment will not execute. The diff will be printed, and validation errors will be reported.
- `--remote <remote>` (bool, default `false`)
  With `--plan`, also extract the proto graph on Chalk's servers and report which materialized windowed aggregate features read different backfilled tiles than the active deployment. This records a deployment that is never activated.
- `--watch <watch>` (bool, default `false`)
  Watch local files for changes and re-apply automatically. Must also supply [`--branch`](https://docs.chalk.ai/cli?command=chalk#branch).
- `--reset <reset>` (bool, default `false`)
  Resets the given branch to the state of the working directory by removing any features or resolvers that were created/updated in a notebook. Must also supply [`--branch`](https://docs.chalk.ai/cli?command=chalk#branch).
- `--deployment-tag <deployment-tag>` (string[], default `[]`)
  Add one or more tags to the deployment (for example, `v0.1.4`).
- `--description <description>` (string)
  A description of the deployment, shown in the dashboard. Markdown is supported.
- `--metadata <metadata>` (string[], default `[]`)
  Attach arbitrary `key=value` metadata to the deployment, shown in the dashboard. Repeat the flag for multiple entries (for example, `--metadata service=fraud --metadata oncall=risk`).
- `--cicd-job-url <cicd-job-url>` (string)
  URL of the CI/CD job producing this deployment. Detected automatically on GitHub Actions, GitLab CI, Buildkite, CircleCI, and Jenkins.
- `--vcs-url <vcs-url>` (string)
  URL of the source repository for this deployment. Detected automatically on GitHub Actions, GitLab CI, Buildkite, CircleCI, and Jenkins.
- `--blue-green <blue>` (bool, default `false`)
  Automatically target the inactive tag in a blue/green deployment (only when blue/green is configured).
- `--skip-requirements-validation <skip-requirements-validation>` (bool, default `false`)
  Skip validation that `requirements.txt` includes the SQL Source extras required by your project.
- `--skip-project-settings-validation <skip-project-settings-validation>` (bool, default `false`)
  Skips project-settings validation performed by '--plan'.
- `--skip-lint <skip-lint>` (bool, default `false`)
  Skip local LSP diagnostics and validation errors, then continue applying.
- `--dump <dump>` (bool, default `false`)
  Print the generated `chalk apply` payload for debugging.

**Example**

```
$ chalk apply
✓ Found resolvers
✓ Successfully validated features and resolvers!
✓ Checked against live resolvers
Added Resolvers

    Name                                       ←    →
────────────────────────────────────────────────────────────
 +  features.underwriting.get_user_details_44  1    1

Added Features

    Name                      Cache?  Owner
────────────────────────────────────────────────────────────
 +  example_user.id
 +  example_user.name
 +  example_user.fraud_score  30m     fraud@company.com

  Would you like to deploy?  [y/n]
```

## `chalk query`
source: https://docs.chalk.ai/cli?command=query

```bash
chalk query [flags]
```

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`](https://docs.chalk.ai/docs/has-one) relationships of `user`.

If you do want to return [`has-one`](https://docs.chalk.ai/docs/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.

**Flags**

- `--in <[feature]=[value]>` (string[], default `[]`)
  Known feature value. Prefix the feature with `.` to disable namespace inference in `--out`. Use `@file(path)` to read the value from a file.

  ```bash
  chalk query --in user.id=1232 --out user.name
  ```

  ```bash
  chalk query --in .user.id=1232 --out .user.name
  ```

  ```bash
  chalk query --in user.data=@file(data.json) --out user.name
  ```
- `--raw-input <raw-input>` (bool, default `false`)
  Treat all input values as raw strings, preventing automatic JSON deserialization. When set, values like `'{"foo":"bar"}'` will be sent as quoted strings instead of JSON objects.
- `--out <feature>` (string[], default `[]`)
  Feature or feature namespace to compute. When a feature namespace is not specified, the namespace will be inferred from `--in` if possible.

  ```bash
  chalk query --in user.id=1232 --out user.name
  ```

  ```bash
  chalk query --in user.id=1232 --out user
  ```

  ```bash
  chalk query --in user.id=1232 --out user.organization.name
  ```

  ```bash
  chalk query --in user.id=1232 --out name
  ```
- `--staleness <[feature]=[duration]>` (string[], default `[]`)
  Specify a [max-staleness](https://docs.chalk.ai/docs/feature-caching) for a feature.

  ```bash
  chalk query --in user.id=1232 --out user.some_feature --staleness user.some_feature=5m
  ```
- `--local <local>` (bool, default `false`)
  Deploy the code to a branch before running the query.
- `--repeat <duration>` (string, default `-1ns`)
  For rapidly changing data (for example, streaming workloads), poll the same query repeatedly. When `--repeat` is set, the CLI runs the query every [`<duration>`](https://docs.chalk.ai/api-docs#Duration).
- `-d, --deployment <deployment>` (string)
  The deployment to query. This flag is useful when you wish to query code that was deployed with `--no-promote`.
- `-n, --query-name <name>` (string)
  Associate a [query name](https://docs.chalk.ai/docs/best-practices#create-named-queries-for-your-commonly-executed-queries) with this request.
- `--query-name-version <query_name_version>` (string)
  Associate a [query name version](https://docs.chalk.ai/docs/best-practices#create-named-queries-for-your-commonly-executed-queries) with this request.
- `--now <now>` (string)
  Override `now` during resolver execution for this query. Pass an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) instant, for example `2023-01-01T09:30:00Z`.
- `--tag <tag>` (string[], default `[]`)
  [Tags](https://docs.chalk.ai/docs/resolver-tags) to use when requesting these features.
- `--store-plan-stages <store-plan-stages>` (bool, default `false`)
  Persistently store all intermediate computed values for debugging. This dramatically decreases performance.
- `-e, --explain <explain>` (bool, default `false`)
  Return an explanation of this query plan.
- `--benchmark <benchmark>` (bool, default `false`)
  Run a benchmark for this query.

  ```bash
  chalk query --in user.id=1232 --out user.name --benchmark --qps=8000 --duration=10s
  ```
- `--trace <trace>` (bool, default `false`)
  Enable tracing of your query results.
- `--qps <qps>` (int, default `1`)
  Queries per second. For use only when `--benchmark` is set.
- `--query-context <query-context>` (string[], default `[]`)
  Immutable key-value context accessible from Python resolvers. Repeat `--query-context key=value` to provide multiple entries.
- `--planner-option <[option]=[value]>` (string[], default `[]`)
  Include a planner option. Repeat this flag to provide many options.

  ```bash
  chalk query --in user.id=1232 --out user.name --planner-option my_option=my_value
  ```
- `--duration <duration>` (string, default `1m0s`)
  Duration to benchmark in seconds. For use only when `--benchmark` is set.
- `--save <save>` (string)
  File to which to save the output of a benchmark. For use only when `--benchmark` is set.
- `--warmup <duration>` (string, default `0s`)
  Warmup duration before collecting benchmark results. For use only when `--benchmark` is set.
- `--bulk <bulk>` (bool, default `false`)
  Use online query with multiple inputs per feature and has-many outputs. With `--bulk`, you can pass `--in` multiple times for the same feature to, for example, pass a list of ids.
- `--correlation-id <correlation-id>` (string)
  Correlation ID to associate with the query request for tracking purposes.
- `--statsd-host <host>` (string)
  StatsD host to send query metrics to. Both `--statsd-host` and `--statsd-port` must be set. See [StatsD](https://github.com/statsd/statsd).
- `--statsd-port <port>` (int, default `0`)
  StatsD port to send query metrics to. Both `--statsd-host` and `--statsd-port` must be set.
- `--translate-fqns <translate-fqns>` (bool, default `false`)
  Translate windowed feature FQNs to human-readable format (e.g. `user.count__86400__` → `user.count[1d]`). Only applies to `--json` output; the interactive display always renders human-readable names.

**Example**

```
$ chalk query --in user.id=1
Using '--out=user'
Results
https://chalk.ai/environments/dmo2ad5trrq3/query-runs/cmdsb2pmp01bj0vavq2f4zvew

 Name                         Hit?  Value
─────────────────────────────────────────────────────────
 user.count_transfers[1d]           2
 user.count_transfers[7d]           4
 user.count_transfers[30d]          7
 user.credit_report_id              123
 user.denylisted                    false
 user.dob                           "1977-08-27"
 user.domain_age_days               10200
 user.domain_name                   "nasa.gov"
 user.email                         "nicoleam@nasa.gov"
 user.email_age_days                2680
 user.email_username                "nicoleam"
 user.id                            1
 user.llm_stability           ✓     "average"
 user.llm_manual_review       ✓     false
 user.name                          "Nicole Mann"
 user.name_email_match_score        75.0
 user.total_spend                   5239.06
```

## `chalk lint`
source: https://docs.chalk.ai/cli?command=lint

```bash
chalk lint [--no-spinners]
```

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`](https://pypi.org/project/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.

**Flags**

- `--local <local>` (bool, default `false`)
  Only perform local validation. Do not call to Chalk for remote validation.
- `--lsp <lsp>` (bool, default `false`)
  Only perform LSP validation; calls remote server.

**Example**

```
$ chalk lint
✓ Found resolvers

Error[153]: SQL file resolver references an output feature
'user.address' which does not exist.
The closest options are 'user.denylisted', 'user.name',
'user.total_spend', 'user.domain_age_days', and 'user.count_transfers'.
   --> src/users.chalk.sql:8:4
4 |     id,
5 |     email,
6 |     dob,
7 |     name,
8 |     address
  |     ^^^^^^^ output feature not recognized
```

## `chalk delete`
source: https://docs.chalk.ai/cli?command=delete

```bash
chalk delete [flags]
```

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](https://docs.chalk.ai/docs/feature-discovery#tags), 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
```

**Flags**

- `--namespace <namespace>` (string)
  The namespace of the feature to be deleted. If not provided, features are expected to be namespace (e.g. `user.name`).
- `--features <features>` (string[], default `[]`)
  The features to be deleted.
- `--tags <tags>` (string[], default `[]`)
  The tags to be deleted.
- `--keys <keys>` (string[], default `[]`)
  Primary keys to be deleted.
- `-f, --force <force>` (bool, default `false`)
  If `true`, skip confirmation before deleting features.

**Example**

```
$ chalk delete --keys=1,2,3 --features user.name,email,age
  Are you sure you want to delete these features?  [y/n]

Successfully deleted features
```

## `chalk migrate-type`
source: https://docs.chalk.ai/cli?command=migrate_type

```bash
chalk migrate-type [flags]
```

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.

**Flags**

- `--features <features>` (string[], default `[]`)
  The features to be deleted.
- `--namespace <namespace>` (string)
  The namespace of the feature to be deleted. If not provided, features are expected to be namespace (e.g. `user.name`).
- `-f, --force <force>` (bool, default `false`)
  If `true`, skip confirmation before deleting features.

**Example**

```
$ chalk migrate-type --features user.name,email,age
The following features will be migrated:

  - user.name
  - user.email
  - user.age

  Are you sure you want to migrate all instances of the features?  [y/n]

Successfully migrated features
```

## `chalk drop-version`
source: https://docs.chalk.ai/cli?command=drop_version

```bash
chalk drop-version [flags]
```

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.

**Flags**

- `--namespace <namespace>` (string)
  The namespace of the feature to be deleted. If not provided, features are expected to be namespace (e.g. `user.name`).
- `--features <features>` (string[], default `[]`)
  The features to be deleted.
- `-f, --force <force>` (bool, default `false`)
  If `true`, skip confirmation before deleting features.

**Example**

```
$ chalk drop-version --features user.name,email,age
Feature version data will be dropped for the following 3 features:

  - user.name
  - user.email
  - user.age

  Are you sure you want to drop all version data for these features?   [y/n]

✓ Successfully dropped version data
```
