---
title: Knock CLI
description: Learn how to use the Knock CLI to build, test, and manage your Knock notification system from the terminal.
section: Developer tools
---

The Knock CLI helps you build, test, and manage your Knock notification system, right from the terminal. You can use the CLI to:

- Pull Knock workflows down to your local machine and work with your notification logic and templates in your code editor.
- [Integrate Knock into your CI/CD pipeline](/tutorials/integrating-into-cicd) and automatically promote changes between Knock environments on release.
- Map your translation files into Knock to localize your notifications.

## Installing the CLI

You can install the Knock CLI using `npm`, a node package manager, with the following command:

```bash title="Installing the Knock CLI"
npm install -g @knocklabs/cli
```

Once the CLI is installed, you can call it by using the `knock` command in your terminal. The CLI is also available via Homebrew for macOS. See [the installation documentation](/cli/overview/installation).

## Authenticating the CLI

### Using your Knock account

You can authenticate your Knock account against the CLI by running `knock login`. This will open a browser window where you can sign in to your Knock account and authorize the CLI to access your account.

Once authenticated, you can verify it works by running `knock whoami`. If your account is valid and configured properly, you'll receive a 200 response that shows the account name and your user ID.

<Callout
  type="beta"
  title="Note:"
  text={
    <>
      Using your Knock account against the CLI will inherit the permissions of
      the user that is logged in on the account you authorized.
    </>
  }
/>

If you need to switch between accounts, you can run `knock logout` to log out of your current account and log in to a different one.

### Using a service token

If you need to authenticate in a remote environment, or want complete control, you can generate a [service token](/developer-tools/service-tokens) in the Knock dashboard.

Once you have generated a service token, you can verify it works by running `knock whoami --service-token=YOUR_SERVICE_TOKEN`. If your token is valid and configured properly, you'll receive a 200 response that shows the account name and the service token name.

## Working with a knock.json file

You can configure the Knock CLI for your project by creating a `knock.json` file or by using the `knock init` command to generate one for you. The `knock.json` file is a project-level configuration file that tells the Knock CLI where to find your Knock resources.

```json title="Example knock.json file"
{
  "knockDir": ".knock"
}
```

Once set, the Knock CLI will use the `knockDir` property for all push and pull commands. Without a `knock.json` file, `knock pull` and `knock push` require the `--knock-dir` flag, while resource-specific commands such as `knock workflow pull` use the current working directory unless you pass that resource's directory flag, for example `--workflows-dir`.

## CLI reference

You can find a complete reference for all of the commands and flags available on the [CLI in our comprehensive reference](/cli/overview).

## Using the CLI with AI coding agents

The `knock-cli` skill packages the CLI docs and patterns into a set of rules that AI agents—such as Cursor and Claude—can use to pull, push, and manage Knock resources directly from your editor.

Install the skill to enable your agent to work with workflows, templates, guides, and partials without needing manual prompting:

```bash
npx skills add knocklabs/skills --skill knock-cli
```

Learn more on the [CLI](/ai/cli) and [skills](/ai/skills) pages.