Agiflow CLI command reference

Reference

The agiflow-cli manages projects, tasks, work units, members, comments, workflows, artifacts, and other supported resources from your terminal. Resource commands return JSON; some workflow and file-transfer commands also print human-readable messages.

This reference follows the 0.2.0 command definitions. Check your installed package version and each command's help before using examples, since released builds can differ. In particular, artifact update changes status or labels, and artifact link accepts a task, a work unit, or both.

Quick answer

Install the Agiflow CLI, authenticate with device-code login or an API key, set optional .agiflowrc defaults, and verify the selected project with a read-only command before making changes.

Maintained by Agiflow. Published 27 May 2026. Last updated 14 Oct 2026.

00 : Install and verify access

In a Node.js project using pnpm, install the CLI and inspect its help. In an existing Agiflow development checkout, use the workspace installation instead of adding another copy. These checks do not change board data.

pnpm add -D @agiflowai/cli@0.2.0
pnpm list @agiflowai/cli
pnpm exec agiflow-cli --help
pnpm exec agiflow-cli login --help
pnpm exec agiflow-cli artifact update --help

Authenticate with browser device-code login, then make a read-only request. Login stores credentials and registers this CLI device; it is not a project creation command. Replace the example project with one returned by the list operation and verify its name and ID before running writes.

pnpm exec agiflow-cli login
pnpm exec agiflow-cli project list --format json
pnpm exec agiflow-cli project get --project YOUR_PROJECT_ID_OR_SLUG --format json

For noninteractive use, supply AGIFLOW_API_KEY through your secret manager or environment instead of pasting it into a command history. Login also accepts --api-key. Use login --global only for intentionally shared local credentials. Logout removes stored credentials for the selected scope; it does not revoke the server-side key or clear environment variables.

01 : Authentication and scope resolution

Credential precedence

AGIFLOW_API_KEY in the environment.
The secret variable named by AGIFLOW_API_KEY_ENV in the environment.
The secret variable referenced by AGIFLOW_API_KEY_ENV in the repository's .agiflowrc.
Stored repository credentials, then stored global credentials.

Stored credentials live in ~/.agiflow/credentials.json with owner-only file permissions. Repository scope uses the Git root, or the working directory outside a repository. Never commit this credentials file.

Organization and project defaults

Explicit --org and --project flags win. Organization defaults then resolve from AGIFLOW_ORGANIZATION_ID or its AGIFLOW_ORG_ID alias, .agiflowrc, and stored credentials. Project defaults resolve from AGIFLOW_PROJECT_ID, then .agiflowrc; they are not stored by login. A default selects a resource, not a permission grant.

Put .agiflowrc at the Git root. The API-key entry below names a secret environment variable, not the secret itself. Set that variable outside version control. Omit the key mapping when using stored login credentials.

AGIFLOW_ORGANIZATION_ID=YOUR_ORGANIZATION_ID
AGIFLOW_PROJECT_ID=YOUR_PROJECT_ID_OR_SLUG
AGIFLOW_API_KEY_ENV=$MY_AGIFLOW_SECRET

Resource and artifact commands accept project IDs or slugs where indicated. Workflow commands use a project ID. For workflow create/check, pass one target explicitly: --work-unit wins over --task when both are supplied; otherwise the fallback checks AGIFLOW_WORK_UNIT_ID before AGIFLOW_TASK_ID. These target defaults are not .agiflowrc fields. Artifact link requires explicit target flags.

02 : Resource commands and global options

Start with the installed help for the resource you need. These groups use JSON output, including structured errors on stdout, and --format json where a format option is exposed. Run mutations only after reviewing the selected resource and requested changes.

project

Create, list, get, update, and delete projects; inspect project statuses.

task

Manage tasks and statuses; find, select, and execute allowed connected tools.

work-unit

Group work, inspect progress, and manage work-unit details.

member

Manage agent members.

task-comment

Read and manage task discussion.

vault

Manage scoped vault environments and entries. Treat values as secrets.

automation

Inspect and manage supported automations.

analytics

Inspect supported analytics.

dependency

Manage work dependencies.

result

Manage supported work results.

pnpm exec agiflow-cli project --help
pnpm exec agiflow-cli task --help
pnpm exec agiflow-cli task list --project YOUR_PROJECT_ID_OR_SLUG --format json
pnpm exec agiflow-cli work-unit list --project YOUR_PROJECT_ID_OR_SLUG --format json

-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.

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

Option

Required

Description

--name <name>

Yes

Workflow name

--org <organizationId>

Organization ID; otherwise environment, .agiflowrc, or stored credentials

--project <projectId>

Project ID; otherwise AGIFLOW_PROJECT_ID or .agiflowrc

--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.

pnpm exec 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.

pnpm exec 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.

pnpm exec 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.

pnpm exec 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.

pnpm exec 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).

workflow delete

Delete workflow metadata. Review the workflow before deleting it; this is not a substitute for releasing a completed lock.

pnpm exec agiflow-cli workflow delete <id> [options]

Option

Required

Description

--org <organizationId>

Organization ID or configured default

--project <projectId>

Project ID or configured default

Output on success

JSON deletion result.

04 : Artifact commands

Manage project artifacts with the artifact command group. All artifact subcommands, including link and update, need an organization and a project. They accept --format json, but upload, downloads, and delete still emit human-readable messages. Scoped downloads append a JSON summary after their progress lines. Use signed-url when a script needs a structured URL response.

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.

pnpm exec 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 by key with --output, or omit the key and explicitly select exactly one of --task and --work-unit. Scoped downloads use --target, not --output.

pnpm exec 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 <projectIdOrSlug>

Project ID or slug

--task <taskId>

Task whose artifacts should be downloaded

--work-unit <workUnitId>

Work unit whose task artifacts should be downloaded

--target <folder>

Target folder for scoped downloads

--overwrite

Allow existing files to be overwritten in scoped downloads

Output on success

Single key: destination message. Scoped downloads: progress messages followed by a JSON summary.

Note: Single-key downloads write directly to the destination and can replace an existing file without --overwrite. Choose a new --output path. The --overwrite safeguard applies only to scoped downloads.

artifact list

List all artifacts for a project.

pnpm exec agiflow-cli artifact list [options]

Option

Required

Description

--org <organizationId>

Organization ID

--project <projectIdOrSlug>

Project ID or slug

--search <search>

Filter by artifact name

--labels <labels>

Comma-separated labels to match

--content-type <contentType>

Content type prefix

--status <status>

pending or uploaded

--max-keys <maxKeys>

Maximum result count

--continuation-token <token>

Continue a paginated result

Output on success

JSON object containing an items array.

artifact get

Get details for a single artifact by key or ID.

pnpm exec 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.

pnpm exec 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 or unlink an artifact to a task, a work unit, or both. Supply at least one target explicitly; environment-only target values do not satisfy this command.

pnpm exec agiflow-cli artifact link <key> [--task <taskId>] [--work-unit <workUnitId>] [options]

Option

Required

Description

--org <organizationId>

Organization ID

--project <projectIdOrSlug>

Project ID or slug

--action <action>

link (default) or unlink

--clip-json <json>

Clip region with x, y, width, and height

--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

JSON result returned by the link_artifact tool.

Note: * At least one of --task or --work-unit is required. Both are supported. Review the targets before linking or unlinking.

artifact seed

Seed artifacts from a JSON file.

pnpm exec 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 an artifact's status or labels through the update_artifact tool. This command performs a remote write.

pnpm exec agiflow-cli artifact update <key> [--status <status>] [--labels <labels>] [options]

Option

Required

Description

--org <organizationId>

Organization ID or configured default

--project <projectIdOrSlug>

Project ID, slug, or configured default

--status <status>

pending or uploaded

--labels <labels>

Comma-separated labels to set

Output on success

JSON result returned by update_artifact.

Note: The current command does not expose a --name flag. Verify the resulting metadata with artifact get.

artifact signed-url

Return a signed storage URL as JSON. Treat that URL as a temporary credential, not a public link.

pnpm exec agiflow-cli artifact signed-url --action <upload|download> [options]

Option

Required

Description

--key <key>

For download

Existing artifact key

--filename <filename>

For upload

Upload filename

--type <type>

Upload content type

--org <organizationId>

Organization ID or configured default

--project <projectIdOrSlug>

Project ID, slug, or configured default

Output on success

JSON URL response with action, and key for a download.

Note: Requesting an upload URL does not upload file bytes or mark an upload complete. Use artifact upload for the complete flow.

05 : Environment variables

AGIFLOW_API_KEY

Authenticated commands, including artifact update

API key for authentication

AGIFLOW_ORGANIZATION_ID

Organization-scoped commands

Default organization ID

AGIFLOW_PROJECT_ID

Project-scoped commands, including artifact link and artifact update

Default project ID

AGIFLOW_TASK_ID

Workflow target fallback; artifact link and scoped downloads require explicit target flags

Default task ID

AGIFLOW_WORK_UNIT_ID

Workflow target fallback; artifact link and scoped downloads require explicit target flags

Default work unit ID

AGIFLOW_API_KEY_ENV

Environment or repository .agiflowrc

Name or $NAME reference to the environment variable holding the API key, not the key itself

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

Resource groups print JSON. Workflow mutations and some artifact commands print success text as well. Do not pipe those mixed-output commands straight into a JSON parser.

Progress messages

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

Errors

Resource groups emit structured JSON errors on stdout and exit with code 1. Workflow and artifact errors generally go to stderr. Login/logout use the requested text or JSON format. Always check the exit status and inspect both streams rather than treating empty output as success.

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