How-to guide
Manage workflow locks
This guide shows you how to acquire, check, and release Agiflow workflow locks from the CLI so only one run is active against a project, work unit, or task at a time.
Last updated
Prerequisites
agiflow-cliis installed and in your PATH- An API key is available via
AGIFLOW_API_KEYor stored credentials - You know your organization ID and project ID
Export these environment variables before running the commands in this guide. Every example below assumes they are set. If you prefer, you can pass --org <id> and --project <id> to each command instead.
export AGIFLOW_ORGANIZATION_ID="org-id" export AGIFLOW_PROJECT_ID="project-id" export AGIFLOW_WORK_UNIT_ID="work-unit-id"
If you need setup help, see the CLI command reference first.
Acquire a lock
Start a new workflow run
Before your script or agent begins work, create a workflow lock. If the same resource is already locked, Agiflow returns a conflict instead of starting duplicate work.
Run this command
agiflow-cli workflow create --name "deploy-staging"
If you want to lock a task instead of a work unit, use --task:
agiflow-cli workflow create --name "run-tests" --task <task-id>
If you did not set AGIFLOW_WORK_UNIT_ID, pass --work-unit explicitly:
agiflow-cli workflow create --name "deploy-staging" --work-unit <work-unit-id>
On success
✓ Workflow lock acquired
{
"id": "wf-01KSH..."
}Save the lock ID — you will need it to release the lock later.
If a lock is already held for the same work unit or task, the CLI returns a 409 conflict with details of the existing lock.
Check a lock
See if a lock is active
Before starting work, you can check whether a lock already exists for a work unit or task.
Run this command
agiflow-cli workflow check --work-unit <work-unit-id>
If you scoped your shell with AGIFLOW_WORK_UNIT_ID, you can omit the flag:
agiflow-cli workflow check
Lock found
The CLI prints the lock details as JSON. Wait for the lock to be released, or choose different work.
✓ Lock found
{
"id": "wf-01KSH...",
"status": "running"
}No lock
The CLI prints an empty JSON object. You are clear to acquire a new lock and start work.
{}Release a lock
Finish the workflow run
Always release the lock when work ends, whether it succeeded or failed. This frees the resource for the next run.
On success
agiflow-cli workflow release <lock-id> --status completed
On failure
agiflow-cli workflow release <lock-id> --status failed --error "Build failed on step 3"
On success
✓ Workflow lock released
{
"id": "wf-01KSH...",
"status": "completed"
}Completed
Use when work finished as expected. The lock is removed and the resource is free.
Failed
Use when work could not finish. Include an error message so logs show why the run stopped.
Tips
Common patterns
Scope with environment variables
Set AGIFLOW_ORGANIZATION_ID, AGIFLOW_PROJECT_ID, and AGIFLOW_WORK_UNIT_ID so you can omit flags from every command.
List recent workflows
Use agiflow-cli workflow list --status running to see what is currently active across your project.
Update context data while a lock is held
Attach progress or metadata to a running lock with agiflow-cli workflow update <lock-id> --context '{"step": 3, "progress": 75}'.