@agiflowai/cli

v0.0.3

Published

14 days ago

Command-line interface for Agiflow workflow and artifact management

0High
0Medium
0Low

Agiflow CLI

agiflow-cli is the command-line interface for working with Agiflow projects, tasks, work units, workflow locks, artifacts, and automation runners.

It is designed for two modes of use:

Humans working in a terminal.
Automation systems that need stable JSON output for job discovery, claiming, and release.

Installation

Run with your package manager:

npx @agiflowai/cli --help

Or install it globally:

npm install -g @agiflowai/cli
agiflow-cli --help

API Endpoint

The CLI must know which Agiflow API to call. Set:

export VITE_INJECT_BACKEND_AGIFLOW_API_ENDPOINT="https://api.example.com"

BACKEND_AGIFLOW_API_ENDPOINT is also accepted as a runtime fallback.

For local development, point the variable at your local Agiflow API.

Authentication

Use device-code login for interactive use:

agiflow-cli login

Use an API key for automation or non-interactive environments:

agiflow-cli login --api-key "$AGIFLOW_API_KEY" --org "$AGIFLOW_ORGANIZATION_ID"

You can also avoid stored credentials and provide an API key through the environment:

export AGIFLOW_API_KEY="..."

To remove stored credentials:

agiflow-cli logout

Common Environment Variables

These variables can replace repeated command flags:

export AGIFLOW_API_KEY="..."
export AGIFLOW_ORGANIZATION_ID="org-id"
export AGIFLOW_PROJECT_ID="project-id"
export AGIFLOW_TASK_ID="task-id"
export AGIFLOW_WORK_UNIT_ID="work-unit-id"
export AGIFLOW_DEVICE_ID="device-id"

Flags take precedence over stored values and environment fallbacks.

Output Formats

Most user-facing commands print readable terminal output or formatted JSON.

Automation and resource commands are JSON-only and require or default to:

--format json

JSON-only command groups:

automation
project
task
work-unit
member
task-comment

Projects

agiflow-cli project list --org "$AGIFLOW_ORGANIZATION_ID" --format json

agiflow-cli project create \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --name "CLI rollout" \
  --description "Release automation work" \
  --format json

agiflow-cli project get --org "$AGIFLOW_ORGANIZATION_ID" --project "$AGIFLOW_PROJECT_ID" --format json

Available project commands:

agiflow-cli project create
agiflow-cli project list
agiflow-cli project get
agiflow-cli project update
agiflow-cli project delete

Tasks

agiflow-cli task create \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID" \
  --title "Implement billing settings" \
  --status todo \
  --priority high \
  --format json

agiflow-cli task list \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID" \
  --status todo,in_progress \
  --limit 20 \
  --format json

Batch create tasks with JSON:

agiflow-cli task batch-create \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID" \
  --tasks-json '[{"title":"First task"},{"title":"Second task"}]' \
  --format json

Available task commands:

agiflow-cli task create
agiflow-cli task batch-create
agiflow-cli task list
agiflow-cli task get
agiflow-cli task active
agiflow-cli task update
agiflow-cli task delete
agiflow-cli task reorder

Work Units

Work units group related tasks into larger chunks of work.

agiflow-cli work-unit batch-create \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID" \
  --work-units-json '[{"title":"Billing settings","type":"feature","priority":"high"}]' \
  --format json

agiflow-cli work-unit list \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID" \
  --status planning \
  --format json

Available work unit commands:

agiflow-cli work-unit batch-create
agiflow-cli work-unit list
agiflow-cli work-unit get
agiflow-cli work-unit update
agiflow-cli work-unit delete
agiflow-cli work-unit progress

Agent Members

Agent members represent automation-capable project participants.

agiflow-cli member list \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --format json

agiflow-cli member create \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --email "[email protected]" \
  --name "Build Agent" \
  --description "Handles build and release work" \
  --format json

Task Comments

agiflow-cli task-comment create \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --task "$AGIFLOW_TASK_ID" \
  --content "Starting implementation." \
  --format json

agiflow-cli task-comment list \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --task "$AGIFLOW_TASK_ID" \
  --format json

Automation Jobs

Automation commands print machine-readable JSON only. They are intended for runners, agents, schedulers, and CI systems.

List runnable jobs:

agiflow-cli automation list-jobs \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID" \
  --status planning,todo \
  --limit 50 \
  --format json

Get a normalized job:

agiflow-cli automation get-job \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID" \
  --job-kind work-unit \
  --job-id "$AGIFLOW_WORK_UNIT_ID" \
  --format json

Claim a job:

agiflow-cli automation claim-job \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID" \
  --job-kind work-unit \
  --job-id "$AGIFLOW_WORK_UNIT_ID" \
  --name "runner-$(date +%Y%m%d%H%M%S)" \
  --device-id "$AGIFLOW_DEVICE_ID" \
  --format json

If a job is already claimed, the command returns JSON with claimed: false instead of printing a stack trace.

Release a claimed job:

agiflow-cli automation release-job \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID" \
  --workflow-id "$WORKFLOW_ID" \
  --status completed \
  --format json

Release with an error:

agiflow-cli automation release-job \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID" \
  --workflow-id "$WORKFLOW_ID" \
  --status failed \
  --error "Build failed" \
  --format json

Filter claimed jobs by runner identity:

agiflow-cli automation list-jobs \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID" \
  --claimed \
  --device-id "$AGIFLOW_DEVICE_ID" \
  --format json

Workflow Locks

Workflow locks are lower-level primitives for coordinating active work.

agiflow-cli workflow create \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID" \
  --work-unit "$AGIFLOW_WORK_UNIT_ID" \
  --name "release-run"

agiflow-cli workflow check \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID" \
  --work-unit "$AGIFLOW_WORK_UNIT_ID"

agiflow-cli workflow release "$WORKFLOW_ID" \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID" \
  --status completed

Available workflow commands:

agiflow-cli workflow create
agiflow-cli workflow get
agiflow-cli workflow list
agiflow-cli workflow update
agiflow-cli workflow release
agiflow-cli workflow check

Artifacts

Artifacts are project files stored through the Agiflow API.

agiflow-cli artifact upload ./report.json \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID" \
  --name report.json \
  --type application/json

agiflow-cli artifact list \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID"

agiflow-cli artifact download "artifact-key" \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID" \
  --output ./report.json

Artifact upload requires artifact storage to be configured on the Agiflow API.

Automation Runner Pattern

A typical runner loop looks like this:

job_json=$(agiflow-cli automation list-jobs \
  --org "$AGIFLOW_ORGANIZATION_ID" \
  --project "$AGIFLOW_PROJECT_ID" \
  --status planning,todo \
  --limit 1 \
  --format json)

job_id=$(printf '%s' "$job_json" | jq -r '.items[0].id // empty')
job_kind=$(printf '%s' "$job_json" | jq -r '.items[0].kind // empty')

if [ -n "$job_id" ]; then
  claim_json=$(agiflow-cli automation claim-job \
    --org "$AGIFLOW_ORGANIZATION_ID" \
    --project "$AGIFLOW_PROJECT_ID" \
    --job-kind "$job_kind" \
    --job-id "$job_id" \
    --name "runner-$(hostname)" \
    --format json)

  workflow_id=$(printf '%s' "$claim_json" | jq -r '.workflowId // empty')

  if [ -n "$workflow_id" ]; then
    # Do the work here.
    agiflow-cli automation release-job \
      --org "$AGIFLOW_ORGANIZATION_ID" \
      --project "$AGIFLOW_PROJECT_ID" \
      --workflow-id "$workflow_id" \
      --status completed \
      --format json
  fi
fi

Troubleshooting

Missing API endpoint

Set the API endpoint:

export VITE_INJECT_BACKEND_AGIFLOW_API_ENDPOINT="https://api.example.com"

Missing API key

Authenticate or provide an API key:

agiflow-cli login

or:

export AGIFLOW_API_KEY="..."

Multiple organizations

Pass the organization explicitly in non-interactive environments:

agiflow-cli login --api-key "$AGIFLOW_API_KEY" --org "$AGIFLOW_ORGANIZATION_ID"

JSON parsing in shell scripts

Use jq for automation commands:

agiflow-cli automation list-jobs --format json | jq '.items'

Help

Use command-specific help to see all available options:

agiflow-cli --help
agiflow-cli automation claim-job --help
agiflow-cli task create --help