Agiflow CLI command reference

Reference

Published 27 May 2026 · Last updated 27 May 2026

The agiflow-cli is the command-line interface for Agiflow workflow and artifact management. It uses Commander.js for argument parsing and prints structured JSON to stdout for machine-readable output.

As of May 2026, the CLI provides six workflow commands (create, get, list, update, release, check) and eight artifact commands (upload, download, list, get, delete, link, seed, update). All workflow commands and most artifact commands are authenticated via API key and scoped to an organization and project. The artifact update command is a placeholder that does not call the API.

01 — Authentication and scope resolution

API key

Most workflow and artifact commands require an API key. The CLI resolves the key in this order:

AGIFLOW_API_KEY environment variable
Stored credentials in ~/.agiflow/credentials.json

If no key is found, the command prints an error to stderr and exits with code 1.

Organization, project, and target scope

Most commands need an organization ID and a project ID. The CLI resolves them in this order:

Command-line flag (--org, --project)
Matching environment variable (AGIFLOW_ORGANIZATION_ID, AGIFLOW_PROJECT_ID)
Stored credentials (organizationId from the credentials file; projectId is env-only)

Workflow commands that target a specific work unit or task resolve the target in this order:

--work-unit or --task flag
AGIFLOW_WORK_UNIT_ID or AGIFLOW_TASK_ID environment variable

Credential storage is scoped per Git repository root when available, otherwise per working directory. The credentials file is created at ~/.agiflow/credentials.json with mode 0o600.

02 — Global options

-v, --verbose

Enable verbose logging.

--debug

Enable debug mode (prints stack traces on error).

03 — Workflow commands

Manage workflow locks with the workflow command group.

agiflow-cli workflow <subcommand> [options]

workflow create

Acquire a workflow lock.

agiflow-cli workflow create --name <name> [options]

Option

Required

Description

--name <name>

Yes

Workflow name

--org <organizationId>

Organization ID (falls back to AGIFLOW_ORGANIZATION_ID or stored credentials)

--project <projectId>

Project ID (falls back to AGIFLOW_PROJECT_ID)

--work-unit <workUnitId>

Work unit ID to associate the lock with

--task <taskId>

Task ID to associate the lock with

--context <json>

Context data as a JSON string

Output on success

✓ Workflow lock acquired
{
  "id": "..."
}

workflow get

Get workflow details by ID.

agiflow-cli workflow get <id> [options]

Option

Required

Description

--org <organizationId>

Organization ID

--project <projectId>

Project ID

Output on success

JSON object with workflow details.

workflow list

List workflows for a project.

agiflow-cli workflow list [options]

Option

Required

Description

--org <organizationId>

Organization ID

--project <projectId>

Project ID

--status <status>

Filter by status: running, completed, or failed

--limit <limit>

Max results (default: 20)

--offset <offset>

Offset for pagination (default: 0)

Output on success

JSON array or paginated result object.

workflow update

Update workflow metadata.

agiflow-cli workflow update <id> [options]

Option

Required

Description

--name <name>

New workflow name

--context <json>

Updated context data as a JSON string

--org <organizationId>

Organization ID

--project <projectId>

Project ID

Output on success

✓ Workflow updated
{ ... }

workflow release

Release a workflow lock.

agiflow-cli workflow release <id> --status <status> [options]

Option

Required

Description

--status <status>

Yes

Release status: completed or failed

--error <error>

Error message (when status is failed)

--org <organizationId>

Organization ID

--project <projectId>

Project ID

Output on success

✓ Workflow lock released
{ ... }

workflow check

Check if a workflow lock exists for a given work unit or task.

agiflow-cli workflow check [options]

Option

Required

Description

--org <organizationId>

Organization ID

--project <projectId>

Project ID

--work-unit <workUnitId>

Work unit ID

--task <taskId>

Task ID

Output on success

Lock found: ✓ Lock found followed by JSON details. Lock not found: {} (empty JSON object).

04 — Artifact commands

Manage project artifacts with the artifact command group.

agiflow-cli artifact <subcommand> [options]

artifact upload

Upload a file as a project artifact. The upload uses a three-step flow: request a presigned URL, PUT the file bytes to storage, then mark the upload complete.

agiflow-cli artifact upload <file> [options]

Option

Required

Description

--name <name>

Artifact name (defaults to the filename)

--type <type>

Content type (defaults to application/octet-stream)

--org <organizationId>

Organization ID

--project <projectId>

Project ID

Output on success

↑ Uploading <name> (<size> bytes)...
✓ Artifact uploaded: <key>

Note: Exits with code 1 if the file path does not exist.

artifact download

Download an artifact by key.

agiflow-cli artifact download <key> [options]

Option

Required

Description

-o, --output <path>

Output file path (defaults to the artifact key)

--org <organizationId>

Organization ID

--project <projectId>

Project ID

Output on success

✓ Downloaded to <path>

artifact list

List all artifacts for a project.

agiflow-cli artifact list [options]

Option

Required

Description

--org <organizationId>

Organization ID

--project <projectId>

Project ID

Output on success

JSON object containing an items array.

artifact get

Get details for a single artifact by key or ID.

agiflow-cli artifact get <key> [options]

Option

Required

Description

--org <organizationId>

Organization ID

--project <projectId>

Project ID

Output on success

JSON object with artifact metadata.

Note: Exits with code 1 if the artifact is not found.

artifact delete

Delete an artifact by key.

agiflow-cli artifact delete <key> [options]

Option

Required

Description

--org <organizationId>

Organization ID

--project <projectId>

Project ID

Output on success

✓ Artifact deleted: <key>

artifact link

Link an artifact to a task or a work unit. You must specify exactly one of --task or --work-unit, not both.

agiflow-cli artifact link <key> (--task <taskId> | --work-unit <workUnitId>) [options]

Option

Required

Description

--org <organizationId>

Organization ID

--task <taskId>

No*

Task ID to link the artifact to

--work-unit <workUnitId>

No*

Work unit ID to link the artifact to

Output on success

{
  "artifactKey": "<key>",
  "linkedTo": {
    "type": "task",
    "id": "<taskId>"
  }
}

Note: * Exactly one of --task or --work-unit is required. Exits with code 1 if both or neither are provided.

artifact seed

Seed artifacts from a JSON file.

agiflow-cli artifact seed --file <path> [options]

Option

Required

Description

--file <path>

Yes

Path to JSON file containing seed data

--org <organizationId>

Organization ID

--project <projectId>

Project ID

Output on success

JSON object with created artifact summary.

Note: Exits with code 1 if the file does not exist or contains invalid JSON.

artifact update

Update artifact metadata.

agiflow-cli artifact update <artifactId> [--name <name>]

Option

Required

Description

--name <name>

New artifact name

Note: This command is a placeholder. The underlying API endpoint is not yet available, and running it prints a warning message.

05 — Environment variables

AGIFLOW_API_KEY

Workflow commands and artifact commands (except artifact update)

API key for authentication

AGIFLOW_ORGANIZATION_ID

Workflow commands and artifact commands (except artifact update)

Default organization ID

AGIFLOW_PROJECT_ID

Workflow commands and project-scoped artifact commands (except artifact link and artifact update)

Default project ID

AGIFLOW_TASK_ID

Workflow target resolution and artifact link

Default task ID

AGIFLOW_WORK_UNIT_ID

Workflow target resolution and artifact link

Default work unit ID

06 — Exit codes

0

Success.

1

Error: missing required argument, authentication failure, API error, file not found, invalid JSON, or upload/download failure. Workflow and artifact commands print errors to stderr and exit with code 1. The workflow check command is a special case: when no lock is found it prints an empty JSON object to stdout and exits with code 0.

07 — Output format

Data responses

Printed as formatted JSON (JSON.stringify(value, null, 2)).

Success messages

Prefixed with a green checkmark (✓).

Progress messages

Prefixed with a blue arrow (↑), for example during upload.

Errors

Printed to stderr with a red cross (✗) and exit code 1.

08 — Related documentation

Manage workflow locks

Step-by-step guide for acquiring and releasing workflow locks.

View page

Project workflows

Concepts for projects, work units, tasks, and workflow locks.

View page