> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/connect/n8n-cli.md).

# n8n CLI

**n8n CLI** is a lightweight command-line client that communicates with a running n8n instance through the [n8n API](/connect/n8n-api.md). It can run from any machine with network access and authenticates using an API key.

{% hint style="info" %}
**n8n CLI is in beta**

Use it only for experimenting, local development, and personal projects and not for production workflows.
{% endhint %}

Use the API CLI to:

* List and inspect workflows
* Create a workflow from JSON
* Check recent executions
* Create a credential
* Manage projects

All operations respect the permissions of the user and the scope of the API key.

## n8n CLI versus server CLI <a href="#n8n-cli-versus-server-cli" id="n8n-cli-versus-server-cli"></a>

If you need to manage your n8n instance (backups, license management, emergency resets), see the [Server CLI](/deploy/host-n8n/configure-n8n/use-the-command-line.md), a built-in tool that runs on the same machine as n8n.

| Aspect                   | n8n CLI                                | Server CLI                               |
| ------------------------ | -------------------------------------- | ---------------------------------------- |
| **Runs from**            | Any machine with network access        | Same machine as n8n                      |
| **Authentication**       | API key                                | Direct database access                   |
| **Requires n8n running** | Yes                                    | No (not required for most operations)    |
| **Best for**             | Developers, integrations, AI agents    | Instance operators, backups, emergencies |
| **Permissions**          | Respects user roles and API key scopes | Bypasses access control                  |

## Install n8n-cli <a href="#install-n8n-cli" id="install-n8n-cli"></a>

```bash
# Use directly with npx (zero install) <a href="#use-directly-with-npx-zero-install" id="use-directly-with-npx-zero-install"></a>
npx @n8n/cli workflow list

# Or install globally <a href="#or-install-globally" id="or-install-globally"></a>
npm install -g @n8n/cli
```

## Connect to your instance <a href="#connect-to-your-instance" id="connect-to-your-instance"></a>

```bash
n8n-cli config set-url https://your-instance.n8n.cloud
n8n-cli config set-api-key YOUR_API_KEY
n8n-cli config show
```

* The configuration is saved to `~/.n8n-cli/config.json` with restricted file permissions (`0600`).
* Get your API key from **n8n > Settings > n8n API**

Alternatively, skip the configuration file and use environment variables:

```bash
export N8N_URL=https://your-instance.n8n.cloud
export N8N_API_KEY=your_api_key
```

## Inline flags <a href="#inline-flags" id="inline-flags"></a>

```bash
n8n-cli --url=https://my-n8n.app.n8n.cloud --api-key=n8n_api_xxxxx workflow list
```

### Resolution order <a href="#resolution-order" id="resolution-order"></a>

1. Command-line flags (`--url`, `--api-key`)
2. Environment variables (`N8N_URL`, `N8N_API_KEY`)
3. Config file (`~/.n8n-cli/config.json`)

## Commands <a href="#commands" id="commands"></a>

Every command supports `--help` for detailed usage.

| Topic              | Commands                                                                                           |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| `workflow`         | `list`, `get`, `create`, `update`, `delete`, `activate`, `deactivate`, `tags`, `transfer`          |
| `execution`        | `list`, `get`, `retry`, `stop`, `delete`                                                           |
| `credential`       | `list`, `get`, `schema`, `create`, `delete`, `transfer`                                            |
| `project`          | `list`, `get`, `create`, `update`, `delete`, `members`, `add-member`, `remove-member`              |
| `tag`              | `list`, `create`, `update`, `delete`                                                               |
| `variable`         | `list`, `create`, `update`, `delete`                                                               |
| `data-table`       | `list`, `get`, `create`, `delete`, `rows`, `add-rows`, `update-rows`, `upsert-rows`, `delete-rows` |
| `user`             | `list`, `get`                                                                                      |
| `config`           | `set-url`, `set-api-key`, `show`                                                                   |
| `source-control`   | `pull`                                                                                             |
| `skill`            | `install`                                                                                          |
| `audit`            | (top-level)                                                                                        |
| `login` / `logout` | (top-level)                                                                                        |

## Output formats <a href="#output-formats" id="output-formats"></a>

All commands support three output formats via `--format`:

| Format  | Flag                       | Use when                                |
| ------- | -------------------------- | --------------------------------------- |
| Table   | -`-format=table` (default) | You want human-readable terminal output |
| JSON    | `--format=json`            | Piping to jq, programmatic use          |
| ID-only | `--format=id-only`         | Piping to xargs, scripting              |

### Examples <a href="#examples" id="examples"></a>

* Human-readable table

  ```bash
  n8n-cli workflow list
  ```
* JSON for scripts

  ```bash
  n8n-cli workflow list --format=json | jq '.[] | select(.active) | .id'
  ```
* Pipe IDs into another command

  ```bash
  n8n-cli workflow list --format=id-only | xargs -I{} n8n-cli workflow deactivate {}
  ```

## Use as skill with Claude Code <a href="#use-as-skill-with-claude-code" id="use-as-skill-with-claude-code"></a>

Install the skill so Claude always knows how to use n8n-cli:

```bash
n8n-cli skill install --global
```

Then in Claude Code, type `/n8n-cli` to load it. Claude can now create, update, and manage workflows on your behalf without requiring an MCP.

## Examples <a href="#examples" id="examples"></a>

### List and inspect workflows <a href="#list-and-inspect-workflows" id="list-and-inspect-workflows"></a>

```bash
n8n-cli workflow list
n8n-cli workflow get <id>
```

### Create a workflow from JSON <a href="#create-a-workflow-from-json" id="create-a-workflow-from-json"></a>

```bash
cat workflow.json | n8n-cli workflow create --stdin
```

### Check recent executions <a href="#check-recent-executions" id="check-recent-executions"></a>

```bash
n8n-cli execution list --status=error --limit=10
```

### Create a credential <a href="#create-a-credential" id="create-a-credential"></a>

```bash
n8n-cli credential schema gmailOAuth2  # see required fields first
n8n-cli credential create --type=gmailOAuth2 --name='My Gmail' --file=cred.json
```

### Manage projects <a href="#manage-projects" id="manage-projects"></a>

```bash
n8n-cli project create --name="My Project"
n8n-cli workflow transfer <id> --project=<projectId>
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.n8n.io/connect/n8n-cli.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.