---
title: 'flexkit automations'
description: 'Create, change, run and version automations from the terminal.'
---

# `flexkit automations`

Manages [automations](/docs/automations): AI agents that follow your instructions on a schedule, on a webhook, when records change, after a job, or on demand. Use it to script automation changes, keep definitions in git, and start runs from CI. To read what a run did, use [`flexkit runs`](/docs/cli/runs); to decide the changes a run proposes, use [`flexkit approvals`](/docs/cli/approvals).

## Synopsis

```bash
flexkit automations <subcommand> [arguments] [options]
```

Without a subcommand, `flexkit automations` runs `ls`. Every subcommand acts on the linked project; pass `--project <id>` to choose another one (see [global options](/docs/cli/global-options)).

## Permissions

| Action                                                         | Roles               |
| -------------------------------------------------------------- | ------------------- |
| `ls`, `inspect`, `tools`, `models`, `credits`, `pull`          | Owner, Developer, Viewer |
| `create`, `update`, `enable`, `disable`, `rm`, `run`, `push`   | Owner, Developer    |

You only see personal automations you created and space automations of spaces you belong to. An automation that uses a **personal** plugin connection can only be saved from a signed-in session (`flexkit login`), not with a project API token.

## `automations ls`

List automations, most recently run first.

```bash
flexkit automations ls [--enabled | --disabled] [--search <text>] [--visibility <list>] [--limit <n>] [--offset <n>] [--json]
```

### Examples

```bash
# List automations in the linked project
flexkit automations ls

# Find enabled automations whose name contains "invoice"
flexkit automations ls --enabled --search invoice

# List your personal and space automations
flexkit automations ls --visibility personal,space

# Print the names of disabled automations
flexkit automations ls --disabled --json | jq -r '.automations[].name'
```

## `automations inspect`

Show one automation: status, model, visibility, data-change policy, triggers (with the webhook URL), attached custom tools and skills, and the instructions.

```bash
flexkit automations inspect <automationId> [--json]
```

### Examples

```bash
# Show an automation
flexkit automations inspect 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f

# Print its webhook URL
flexkit automations inspect 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f --json \
  | jq -r '.automation.triggers[] | select(.type == "webhook") | .url'
```

## `automations create`

Create an automation from flags, from a JSON definition, or both (flags override the file). New automations are **disabled** unless you pass `--enable`, so you can test them with `automations run` first. Defaults: model `auto`, visibility `project`, data changes require approval.

```bash
flexkit automations create --name <name> --instructions <text|file> [--schedule <cron>]... [--timezone <tz>] [--model <id>] [--visibility <v>] [--space <id>] [--mutation-policy <policy>] [--enable] [--file <json>] [--json]
```

`--instructions` (alias `--prompt`) takes inline text, a file path, `@file`, or `-` for stdin. `--schedule` adds a schedule trigger and can be repeated; use `--file` for webhook, entity, job and poll triggers (see the [definition format](#definition-format)).

### Examples

```bash
# A weekday report at 8:00 Madrid time, enabled right away
flexkit automations create --name "Daily stock report" \
  --instructions "Summarize products with stock below 10 and post the list." \
  --schedule "0 8 * * 1-5" --timezone Europe/Madrid --enable

# Instructions kept in a Markdown file
flexkit automations create --name "Weekly churn review" --instructions @prompts/churn.md

# From a JSON definition
flexkit automations create --file automations/stock-report.json

# Copy an automation into another project
flexkit automations pull 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f - \
  | flexkit automations create --file - --project prod-project-id
```

## `automations update`

Change an automation. Only what you pass changes: the CLI loads the current definition and applies the fields of `--file` and the flags on top. Lists are replaced as a whole, so to change triggers or plugin tools put the complete `triggers` or `toolConfigs` list in `--file`.

```bash
flexkit automations update <automationId> [--name <name>] [--instructions <text|file>] [--model <id>] [--visibility <v>] [--space <id>] [--mutation-policy <policy>] [--enable | --disable] [--file <json>] [--json]
```

### Examples

```bash
# Rename
flexkit automations update 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f --name "Stock report (EU)"

# Replace the instructions from a file
flexkit automations update 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f --instructions @prompts/stock-report.md

# Let the agent apply data changes without asking
flexkit automations update 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f --mutation-policy auto_approve

# Replace the triggers with one daily schedule
echo '{"triggers":[{"type":"schedule","cron":"0 7 * * *","timezone":"UTC"}]}' \
  | flexkit automations update 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f --file -
```

## `automations enable` / `automations disable`

Turn an automation's triggers on or off. A disabled automation can still be run by hand.

```bash
flexkit automations enable <automationId> [--json]
flexkit automations disable <automationId> [--json]
```

### Examples

```bash
# Enable after a successful test run
flexkit automations enable 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f

# Pause an automation
flexkit automations disable 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f
```

## `automations rm`

Delete an automation and its triggers. Past runs stay in the run history. The CLI asks for confirmation; pass `--yes` in scripts.

```bash
flexkit automations rm <automationId> [--yes] [--json]
```

### Examples

```bash
# Delete after a prompt
flexkit automations rm 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f

# Delete without a prompt
flexkit automations rm 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f --yes
```

## `automations run`

Start a manual run now. The automation does not need to be enabled. By default the command prints the run id and returns. With `--follow` it streams the run's events (as [`runs logs --follow`](/docs/cli/runs#runs-logs) does); with `--wait` it waits silently and prints the run summary. Both keep waiting while the run waits for an approval, and exit with code 1 when the run fails or is cancelled.

```bash
flexkit automations run <automationId> [--follow | --wait] [--json]
```

### Examples

```bash
# Start a run
flexkit automations run 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f

# Start a run and watch it
flexkit automations run 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f --follow

# In CI: fail the job when the run fails, keep the summary
flexkit automations run 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f --wait --json | jq -r '.run.summary'
```

## `automations tools`

Show what an automation can use: the project's custom tools and which of them are attached, its plugin settings, Slack and Teams delivery channels, and attached skills.

```bash
flexkit automations tools <automationId> [--json]
```

### Examples

```bash
# Show the tools of an automation
flexkit automations tools 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f

# Print the attached custom tools
flexkit automations tools 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f --json | jq -r '.customToolNames[]'
```

## `automations models`

List the models automations can use. Pass the `ID` column to `--model`; `auto` lets Flexkit choose per run. To use another reasoning effort, pass `<model>:<effort>` with one of the listed efforts.

```bash
flexkit automations models [--json]
```

### Examples

```bash
# List models
flexkit automations models

# Use a specific model with high effort
flexkit automations update 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f --model anthropic/claude-opus-5.5:high
```

## `automations credits`

Show the AI credit balance of the project's team. Automation runs draw from it.

```bash
flexkit automations credits [--json]
```

### Examples

```bash
# Show the balance and the top-up link
flexkit automations credits

# Check for a low balance in a script
flexkit automations credits --json | jq '.creditBalance.isLowBalance'
```

## `automations pull`

Save an automation's definition as JSON, for version control or for copying it to another project. Without a file, or with `-`, it is printed on stdout.

```bash
flexkit automations pull <automationId> [file]
```

The file includes webhook tokens and secrets. Keep such files out of public repositories.

### Examples

```bash
# Save to a file in your repository
flexkit automations pull 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f automations/stock-report.json

# Print it
flexkit automations pull 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f
```

## `automations push`

Apply a definition saved with `pull`. When the file has an `id`, that automation is updated; otherwise (or with `--create`) a new automation is created and its id printed.

```bash
flexkit automations push <file> [--create] [--json]
```

### Examples

```bash
# Apply a changed definition
flexkit automations push automations/stock-report.json

# Create a copy in another project
flexkit automations push automations/stock-report.json --create --project prod-project-id
```

## Definition format

`--file`, `pull` and `push` use the same JSON object as the automations API. Fields you leave out keep their current value on update, or their default on create.

```json
{
  "id": "3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f",
  "name": "Daily stock report",
  "instructions": "Summarize products with stock below 10 and post the list.",
  "enabled": true,
  "modelId": "auto",
  "visibility": "project",
  "spaceId": null,
  "mutationPolicy": "require_approval",
  "notifyRule": "when_flagged",
  "notifyCreator": true,
  "customToolNames": ["forecastDemand"],
  "skillIds": [],
  "toolConfigs": [],
  "triggers": [
    { "type": "schedule", "cron": "0 8 * * 1-5", "timezone": "Europe/Madrid" },
    { "type": "entity", "entities": ["Product"], "events": ["update"] },
    { "type": "webhook", "token": "stock-report-hook-01", "secret": null },
    { "type": "job", "job": "schema_deploy", "outcome": "failed", "automationId": null },
    { "type": "poll", "query": "{ orders(where: { status: { eq: \"pending\" } }) { _id } }", "intervalMinutes": 15, "condition": null, "variables": null }
  ]
}
```

- `visibility`: `project`, `space` (with `spaceId`) or `personal`.
- `mutationPolicy`: `require_approval` or `auto_approve`.
- `notifyRule`: `always`, `when_flagged`, `failures` or `never`.
- Triggers are described in [Automation triggers](/docs/automations/triggers). A webhook token is 8–128 letters, digits, `_` or `-`; only one webhook trigger is allowed.

## Options

| Option                         | Description                                                                         |
| ------------------------------ | ----------------------------------------------------------------------------------- |
| `--json`                       | Print the API response as JSON on stdout.                                            |
| `-p, --project <id>`           | Project to act on (default: the linked project).                                     |
| `-y, --yes`                    | Skip the confirmation of `rm`.                                                       |
| `--enabled`, `--disabled`      | `ls`: only enabled or disabled automations.                                          |
| `-q, --search <text>`          | `ls`: only automations whose name contains the text.                                 |
| `--visibility <v>`             | `ls`: comma-separated filter. `create`/`update`: `project`, `space` or `personal`.   |
| `-n, --limit <n>`              | `ls`: number of automations (default 25, max 100).                                   |
| `--offset <n>`                 | `ls`: number of automations to skip.                                                 |
| `-f, --file <json>`            | `create`/`update`: definition as a file path, `@file`, `-` (stdin) or inline JSON.    |
| `--name <name>`                | `create`/`update`: name.                                                             |
| `-i, --instructions <text>`    | `create`/`update`: instructions as text, a file path, `@file` or `-`. Alias `--prompt`. |
| `-m, --model <id>`             | `create`/`update`: model id from `automations models` (default `auto`).              |
| `--space <id>`                 | `create`/`update`: space of a space automation; implies `--visibility space`.        |
| `--mutation-policy <policy>`   | `create`/`update`: `require_approval` (default) or `auto_approve`.                   |
| `--schedule <cron>`            | `create`: add a schedule trigger (repeatable).                                       |
| `--timezone <tz>`              | `create`: IANA timezone of the `--schedule` triggers (default `UTC`).                |
| `--enable`, `--disable`        | `create`: enable right away. `update`: enable or disable.                            |
| `-f, --follow`                 | `run`: stream the run's events until it finishes.                                    |
| `-w, --wait`                   | `run`: wait until the run finishes and print its summary.                            |
| `--create`                     | `push`: always create a new automation.                                              |

You can also use all [global options](/docs/cli/global-options).

## Common workflows

### Keep automations in git

```bash
# Save every automation of the project
flexkit automations ls --json --limit 100 | jq -r '.automations[].id' | while read -r id; do
  flexkit automations pull "$id" "automations/$id.json"
done

# After editing a file, apply it
flexkit automations push automations/3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f.json
```

### Test before enabling

```bash
# Create disabled, run once and read the result, then enable
id=$(flexkit automations create --name "Tag new orders" --instructions @prompts/tag-orders.md --json | jq -r '.automation.id')
flexkit automations run "$id" --follow
flexkit automations enable "$id"
```


---

[View full sitemap](/docs/sitemap.md)