# Chalk CLI Reference: Setup
source: https://docs.chalk.ai/cli#setup

Configure your local environment, authenticate with Chalk, and manage [project settings](https://docs.chalk.ai/docs/docker). These commands help you connect to your Chalk deployment and set up your development workflow.

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

```bash
chalk login [--no-prompt]
```

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`](https://wiki.archlinux.org/title/XDG_Base_Directory) environment variable to override this location.

**Flags**

- `--no-prompt <no-prompt>` (bool, default `false`)
  If set, Chalk will open the CLI authorization window in your browser without asking. Useful for automated scripts.

**Example**

```
$ chalk login
✓ Created session

  Open the authorization page in your browser?  Yes

Complete authorization at https://chalk.ai/cli/ls-cldtwriw700ds62e07sr55
✓ Opened login window in browser
⡿  Waiting...
```

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

```bash
chalk environment <env>
```

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

In Chalk, each team has many projects, and each project has many environments.

Outside a Chalk project, select a project and environment interactively. The selection is saved for the current directory without creating chalk.yaml. Use --json to list environments across projects without prompting.

Within an environment, you may define different data sources and different [resolvers](https://docs.chalk.ai/docs/resolver-environments).

**Arguments**

- `env` (string)
  The name of the environment to activate. When `<env>` is not specified, this command opens an environment picker; --json prints the available and active environments.

**Example**

```
$ chalk environment prod
✓ Fetched available environments
✓ Set environment to 'prod'
```

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

```bash
chalk config
```

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`](https://docs.chalk.ai/cli?command=login), Chalk stores your client ID and secret in `~/.config.yml` (unless overridden by the [XDG_CONFIG_HOME](https://wiki.archlinux.org/title/XDG_Base_Directory) environment variable).

The config will change according to the active environment (determined by [`chalk environment`](https://docs.chalk.ai/cli?command=environment) and active project (determined by [`chalk project`](https://docs.chalk.ai/cli?command=project).

Use `--format` to control the output format:

- `table` (default): human-readable table
- `json`: JSON object
- `env`: .env file format (KEY=VALUE)
- `shell`: shell export statements
- `chalkpy`: Python ChalkClient constructor

Client secrets are hidden by default. Pass `--show-secrets` to reveal them. The `env`, `shell`, and `chalkpy` formats require `--show-secrets` because their output contains working credentials.

**Flags**

- `-f, --format <format>` (string)
  Output format: table, json, env, shell, chalkpy
- `--show-secrets <show-secrets>` (bool, default `false`)
  Show the client secret in output

**Example**

```
$ chalk config
 Name             Value                                  Source
───────────────────────────────────────────────────────────────────────
 Client ID        token-392c737aa1e467e42e85ae3e8417a003 default token
 Client Secret    <set>                                  default token
 Environment      btfxgaqqxbt7z                          default token
 Environment Name default                                default token
 API Server       https://api.chalk.ai                   default token
 GRPC API Server  https://api.chalk.ai                   default token
 Query Server     https://api.chalk.ai                   default token

$ chalk config --format shell --show-secrets
export CHALK_CLIENT_ID=token-392c737aa1e467e42e85ae3e8417a003
export CHALK_CLIENT_SECRET=<client-secret>
export CHALK_ENVIRONMENT=btfxgaqqxbt7z
export CHALK_API_SERVER=https://api.chalk.ai
```

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

```bash
chalk init
```

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.

When you are logged in, the project name comes from your login (the projects [`chalk whoami`](https://docs.chalk.ai/cli?command=whoami) reports). A login with one project uses it without prompting; with several, `init` asks you to pick one, offering the project that owns your active environment first. Logged out, `init` asks for a name.

Projects are managed with `uv`. When it is not installed, `init` offers to install it from [https://astral.sh/uv](https://astral.sh/uv) before creating `pyproject.toml`. The installer adds `uv` to the PATH of new shells only; `init` uses it by full path and tells you how to load it into your current shell. Non-interactive sessions use `uv` without prompting.

`init` then asks which coding agent you use (Claude Code, Codex, or both) and, for each one, writes its Chalk instruction file, registers the Chalk MCP server using your login (as [`chalk mcp configure-claude`](https://docs.chalk.ai/cli?command=mcp%20configure-claude) and [`chalk mcp configure-codex`](https://docs.chalk.ai/cli?command=mcp%20configure-codex) do), and installs every Chalk skill into the agent's project-local skills directory. These steps are skipped in non-interactive sessions.

For a new project, the dev dependency group includes `pandas<3` for local offline-query snippets. Finally, `init` adds `chalkcompute` and `chalkpy` to the project's dependencies and runs `uv sync`. Installation failures return an error so setup is not reported as complete. `chalkcompute` is published for macOS (arm64, x86_64), Linux (x86_64, aarch64), and Windows x86_64, so it is added with an environment marker and `init` reports it as skipped elsewhere.

To configure AI assistant prompts on their own, use `chalk init agent-prompt [provider]`. To install reusable coding-agent skills on their own, use `chalk install agent-skill`.

**Flags**

- `--show-settings <show-settings>` (bool, default `false`)
  Print Chalk's recommended pyproject.toml and editor settings for files that already existed and were left untouched.

**Example**

```
$ chalk init

Project files
  ✓ .chalkignore              created
  ✓ .gitignore                created
  ✓ README.md                 created
  ✓ chalk.yaml                created for project "fraud" from your login

Dependencies
  ✓ uv              /Users/me/.local/bin/uv
  ✓ pyproject.toml  configured for uv and Chalk typechecking
  ✓ chalkcompute, chalkpy  installed

Editors
  ✓ VS Code, Zed, Helix  created .vscode/settings.json, .vscode/extensions.json, .zed/settings.json, .helix/languages.toml

Coding agents
  Claude Code
    ✓ CLAUDE.md   created with Chalk-specific instructions
    ✓ MCP server  registered "chalk" (user scope)
    ✓ skills      7 installed in .claude/skills
```

## `chalk init agent_prompt`
source: https://docs.chalk.ai/cli?command=init_agent_prompt

```bash
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
- **codex** - Creates `AGENTS.md` for Codex
- **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.

**Arguments**

- `provider` (string)
  The AI assistant provider to configure. Supported values: `cursor`, `claude`, `codex`, `copilot`, and `augment`.

**Example**

```
$ chalk init agent-prompt cursor
Created AGENTS.md with Chalk-specific context for Cursor IDE
        
$ chalk init agent-prompt claude
Created CLAUDE.md with Chalk-specific context for Claude AI
        
$ chalk init agent-prompt copilot
Created .github/copilot-instructions.md with Chalk-specific context for GitHub Copilot

$ chalk init agent-prompt augment
Created .augment/rules/chalk-guidelines.md with Chalk-specific context for Augment
```

## `chalk install agent_skill`
source: https://docs.chalk.ai/cli?command=install_agent_skill

```bash
chalk install agent-skill [skill...]
```

Install reusable Chalk instruction skills for Codex, Claude Code, Cursor, or a custom skills directory.

Skills are always fetched from the `main` branch of `chalk-ai/agent-prompts`. Project-local installation is the default; use `--global` for the selected agents' user-level directories. Re-running the command updates changed files and leaves current files untouched.

**Arguments**

- `skill...` (string)
  One or more skills from `chalk-ai/agent-prompts`. Omit in a terminal to browse interactively.

**Flags**

- `--codex <codex>` (bool, default `false`)
  Install for Codex. Uses `.agents/skills` in the current directory, or `$CODEX_HOME/skills` with `--global`.
- `--claude <claude>` (bool, default `false`)
  Install for Claude Code. Uses `.claude/skills` in the current directory, or `~/.claude/skills` with `--global`.
- `--cursor <cursor>` (bool, default `false`)
  Install for Cursor. Uses `.cursor/skills` in the current directory, or `~/.cursor/skills` with `--global`.
- `--global <global>` (bool, default `false`)
  Install in the selected agents' user-level skill directories instead of the current project.
- `--path <directory>` (string)
  Also install beneath this custom skills directory. Relative paths are resolved from the current directory.
- `--delete <delete>` (bool, default `false`)
  Delete the selected skills' `SKILL.md` files instead of installing them. Empty skill directories are removed.

**Example**

```
# Install the notebook skill in this project's Codex directory
$ chalk install agent-skill chalk-notebooks --codex

# Install several skills for Codex, Claude Code, and Cursor
$ chalk install agent-skill chalk-notebooks writing-static-chalkdf --codex --claude --cursor

# Install globally for Codex
$ chalk install agent-skill chalk-notebooks --codex --global

# Remove an installed skill
$ chalk install agent-skill chalk-notebooks --codex --delete
```

## `chalk mcp configure_claude`
source: https://docs.chalk.ai/cli?command=mcp_configure_claude

```bash
chalk mcp configure-claude
```

Register the Chalk MCP server with Claude Code, using the credentials the CLI is already authenticated with.

This registers a dynamic header helper that reads the client ID and secret from [`chalk config`](https://docs.chalk.ai/cli?command=config) whenever Claude Code connects. Claude Code's configuration stores the client ID for diagnostics and a `[redacted]` placeholder instead of the client secret, so `claude mcp get` can show both header names safely. The helper pins the current directory so it resolves the same directory-scoped Chalk credentials from every Claude Code project.

The endpoint defaults to the active API server plus `/v1/mcp/sse`; override it with `--url` for isolated deployments.

The server is registered in Claude Code's `user` scope by default, so it is available in every project. Pass `--claude-scope local` to limit it to the current directory, or `--claude-scope project` to write it to `.mcp.json` for your teammates.

**Flags**

- `--name <name>` (string, default `chalk`)
  Name to register the Chalk MCP server under.
- `--url <url>` (string)
  Override the MCP endpoint. Defaults to the active API server plus `/v1/mcp/sse`.
- `--claude-scope <scope>` (string, default `user`)
  Scope Claude Code stores the server in: `user` (every project), `local` (only this directory), or `project` (shared with teammates through `.mcp.json`).
- `--force <force>` (bool, default `false`)
  Replace an existing server with the same name instead of failing.
- `--dry-run <dry-run>` (bool, default `false`)
  Print credential-safe configuration instead of applying it.

**Example**

```
# Register the Chalk MCP server for every project
$ chalk mcp configure-claude
✓ Added MCP server "chalk" to Claude Code (user scope)

# Limit it to the current directory, replacing any existing registration
$ chalk mcp configure-claude --claude-scope local --force

# See the secret-safe registration command without running it
$ chalk mcp configure-claude --dry-run
claude mcp add-json --scope user chalk '{"type":"http","url":"https://api.chalk.ai/v1/mcp/sse","headers":{"X-Chalk-Client-Id":"token-...","X-Chalk-Client-Secret":"[redacted]"},"headersHelper":"chalk --skip-version-check --dir /path/to/project mcp auth-headers --json"}'
```

## `chalk mcp configure_codex`
source: https://docs.chalk.ai/cli?command=mcp_configure_codex

```bash
chalk mcp configure-codex
```

Register the Chalk MCP server with Codex, using the credentials the CLI is already authenticated with.

Unlike Claude Code, `codex mcp add` has no `--header` flag — a streamable HTTP server only takes a bearer token or OAuth on the command line — so this command writes an `[mcp_servers.<name>]` block into Codex's `config.toml` directly. Only that block is rewritten; the rest of the file, comments included, is left untouched.

By default the client ID and secret from [`chalk config`](https://docs.chalk.ai/cli?command=config) are written into the file as `http_headers`, which works with no further setup. Pass `--env-headers` to emit `env_http_headers` instead, which references the `CHALK_CLIENT_ID` and `CHALK_CLIENT_SECRET` environment variables so no secret is stored on disk — pair it with `eval "$(chalk config --format shell --show-secrets)"`.

Codex has no per-project scope: the file is global, at `$CODEX_HOME/config.toml` or `~/.codex/config.toml`. Override it with `--codex-config`.

**Flags**

- `--name <name>` (string, default `chalk`)
  Name to register the Chalk MCP server under.
- `--url <url>` (string)
  Override the MCP endpoint. Defaults to the active API server plus `/v1/mcp/sse`.
- `--codex-config <path>` (string)
  Path to Codex's `config.toml`. Defaults to `$CODEX_HOME/config.toml`, or `~/.codex/config.toml`.
- `--env-headers <env-headers>` (bool, default `false`)
  Reference the `CHALK_CLIENT_ID` and `CHALK_CLIENT_SECRET` environment variables instead of writing the credentials into `config.toml`.
- `--force <force>` (bool, default `false`)
  Replace an existing server with the same name instead of failing.
- `--dry-run <dry-run>` (bool, default `false`)
  Print credential-safe configuration instead of applying it.

**Example**

```
# Write the credentials into ~/.codex/config.toml
$ chalk mcp configure-codex
✓ Added MCP server "chalk" to /Users/me/.codex/config.toml

# Reference environment variables instead of storing the secret
$ chalk mcp configure-codex --env-headers
$ eval "$(chalk config --format shell --show-secrets)"

# Replace an existing block
$ chalk mcp configure-codex --force

# See the TOML that would be written, with the credentials redacted
$ chalk mcp configure-codex --dry-run
[mcp_servers.chalk]
url = "https://api.chalk.ai/v1/mcp/sse"
http_headers = { "X-Chalk-Client-Id" = "<redacted>", "X-Chalk-Client-Secret" = "<redacted>" }
```

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

```bash
chalk project [--edit]
```

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`](https://docs.chalk.ai/docs/docker) or [`chalk.yaml`](https://docs.chalk.ai/docs/docker) 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](https://docs.chalk.ai/docs/docker#extra-pip-dependencies)
- [Python runtime](https://docs.chalk.ai/docs/docker#python-version)
- [Dockerfile](https://docs.chalk.ai/docs/docker)
- [Validation settings](https://docs.chalk.ai/docs/validation)

Your current working directory (or any parent directory) must contain a [`chalk.yml`](https://docs.chalk.ai/docs/docker) or [`chalk.yaml`](https://docs.chalk.ai/docs/docker) file.

**Flags**

- `-e, --edit <edit>` (bool, default `false`)
  Opens the configuration file in your default editor.

**Example**

```
$ chalk project
Name: Credit

Environment: default
  Requirements: requirements.txt
  Runtime: python311

Environment: staging
  Requirements: requirements-staging.txt
  Runtime: python311
```

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

```bash
chalk infra
```

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`](https://docs.chalk.ai/cli?command=environment) and active project (determined by [`chalk project`](https://docs.chalk.ai/cli?command=project).

## `chalk offline-store`
source: https://docs.chalk.ai/cli?command=offline_store

```bash
chalk offline-store
```

Use the `offline-store` commands to manage offline stores for your Chalk environments.
