Managing Automations via CLI

The markdocket CLI lets you manage automations entirely from the command line — useful for scripting, CI pipelines, version-controlled automation definitions, and bulk operations. This page covers the full lifecycle: listing, creating, updating, running, and understanding how the CLI protects against concurrent edits.

Prerequisites

Before using automation commands, make sure you are authenticated:

markdocket login

You need an active session (browser OAuth) or a personal API key configured. See the authentication guide for details.

Listing automations

Retrieve all automations in your account:

markdocket automations list

Each automation entry includes its ID, name, status, and the updatedAt timestamp. Keep note of the ID — you will need it for update, run, and delete operations.

Creating an automation

Create a new automation from a JSON definition file:

markdocket automations create --file automation.json

Or pass a minimal definition inline:

markdocket automations create --name "Watch for Office Actions" --trigger deadline

On success, the CLI prints the newly created automation's ID and updatedAt timestamp. Save the ID — it is required for all subsequent operations on that automation.

Updating an automation

markdocket automations update --id <automation-id> [options]

You can supply update fields inline or via a file:

# Inline rename
markdocket automations update --id aut_abc123 --name "Revised Office Action Watch"

# From a file containing only the fields to change
markdocket automations update --id aut_abc123 --file changes.json

How the update works internally

Every automations update call performs a read-before-write sequence:

1. The CLI fetches the current automation from the server to retrieve its live updatedAt timestamp.
2. It sends the update payload together with that timestamp as expectedUpdatedAt.
3. The server accepts the update only if the automation has not been modified since that timestamp was read.
4. If a concurrent change has occurred, the server rejects the update and the CLI reports a conflict error.

This pattern — called optimistic concurrency control — means you will never silently overwrite a change made by another session, team member, or concurrent automation run between the time you read the definition and the time you write it back.

Optimistic concurrency in detail

Optimistic concurrency protection is always active for automation updates through the CLI. You do not need to pass any extra flags.

What triggers a conflict?

A conflict is raised when the automation's updatedAt value on the server differs from the one the CLI read before sending the update. This happens if:

• Another user (or another CLI session) updated the same automation while you were editing.
• An automated run modified the automation's state between your read and write.
• You supplied a stale automation ID from a cached or old export.

Resolving a conflict

When a conflict is detected, the CLI exits with a non-zero status and prints a message such as:

Conflict: automation aut_abc123 was updated after you fetched it.
Re-run `markdocket automations update` to apply your changes against the latest version.

To resolve:

1. Run markdocket automations get --id <automation-id> to review what changed.
2. Reconcile your intended changes with the current server state.
3. Re-run markdocket automations update — the CLI will fetch a fresh timestamp automatically.

Using --file safely

Because expectedUpdatedAt is always read live and never taken from the file, you can safely store automation definitions as JSON in version control without worrying that a stale updatedAt field in the file will cause incorrect behavior. The CLI discards those fields if present and fetches fresh values instead.

{
  "name": "Office Action Monitor",
  "nodes": [
    { "type": "trigger", "event": "deadline" },
    { "type": "agent", "prompt": "Summarize any new office actions for {{vars.mark}}" }
  ]
}

The file above contains only the fields you want to set — no automationId, no updatedAt. Pass it directly:

markdocket automations update --id aut_abc123 --file automation.json

Running an automation

Trigger a manual run of an existing automation:

markdocket automations run --id <automation-id>

The CLI starts the run and returns a run ID. Automation runs execute as durable background jobs — individual graph nodes are checkpointed, so a run can survive transient failures and resume from the last completed node.

Monitoring a run

markdocket automations runs list --id <automation-id>

This lists recent runs for the automation, including status and per-node outcomes. You can also view run traces in the web dashboard's automation builder, which overlays step results directly on the visual graph.

Run concurrency limits

At most 2 automation runs per user can execute simultaneously across all automations. Runs that exceed this limit are queued until a slot is available.

Getting a single automation

Fetch the full definition and metadata for one automation:

markdocket automations get --id <automation-id>

The output includes the current updatedAt timestamp, node graph, trigger configuration, and the status of the most recent run.

Deleting an automation

markdocket automations delete --id <automation-id>

This action is permanent. Confirm the automation ID before running.

Scripting and CI usage

Because the CLI returns structured output, you can integrate automation management into scripts and pipelines.

Example: update from CI

#!/bin/bash
set -euo pipefail

AUTOMATION_ID="aut_abc123"

# Apply definition from repo
markdocket automations update \
  --id "$AUTOMATION_ID" \
  --file ./automations/office-action-monitor.json

echo "Automation updated successfully."

Because the CLI always performs a live read before writing, this script is safe to run in parallel from multiple CI jobs — only one write will succeed at a time, and the others will receive a conflict error rather than silently overwriting each other.

Exiting on conflict in scripts

The CLI exits with a non-zero code on conflict, so set -e or standard error handling in your pipeline will catch it automatically. Retry logic is your responsibility — a simple retry loop is usually sufficient:

for attempt in 1 2 3; do
  markdocket automations update --id "$AUTOMATION_ID" --file ./automation.json && break
  echo "Attempt $attempt failed, retrying..."
  sleep 2
done

Billing considerations

Automation runs consume credits based on the nodes they execute. Agent nodes (which invoke the AI agent) consume more credits than catalog action nodes. If a run encounters a billing limit, it is suspended — not failed — and can be resumed once billing is resolved. A suspended run retains all completed node results.

If you have configured BYOK (Bring Your Own Key) AI credentials, they apply only to agent nodes inside automation runs and do not affect other CLI operations.

Summary of commands

Related pages

• CLI Authentication
• Building Automations in the Dashboard
• Automation Node Types
• BYOK AI Credentials