aio-ffcpe-cli

aio-cli-plugin-ffcpe (FFCPE CLI)

This repository is an oclif plugin for Adobe I/O CLI. Topic: ffcpe — Firefly Creative Production for Enterprise (FFCPE) — focused on the run-workflow Catalog API for custom actions.

Legacy language: internal and older docs sometimes say Workflow Builder or used older topic naming in screenshots. That is the same capability; current branding and the aio topic are ffcpe.

When to use this skill

• Installing or troubleshooting the plugin
• Choosing the right aio ffcpe catalog … command
• Explaining flags (--base-url, --org-id, --api-key, --json, etc.)
• How auth and org context are resolved

Setup

1. Install Adobe I/O CLI (aio)

Requires Node.js 18+.

npm install -g @adobe/aio-cli
aio --version

2. Install this plugin (@adobe/aio-cli-plugin-ffcpe)

aio plugins:install @adobe/aio-cli-plugin-ffcpe

Or from Git (fork or internal repo):

aio plugins:install https://github.com/adobe/aio-cli-plugin-ffcpe

3. Verify and authenticate

aio ffcpe catalog --help
aio login
aio console org select

If aio ffcpe is missing, run aio plugins and confirm this package is installed.

Base URL

• Default: https://run-workflow.adobe.io
• Override: environment variable AIO_FFCPE_CATALOG_BASE_URL or flag --base-url (-u) on catalog commands.

Commands (catalog)

Command	Purpose
aio ffcpe catalog validate	Local validation of catalog entry JSON (typically <action-name>.entry.json). Use --file / -f.
aio ffcpe catalog register	POST a new catalog entry from a JSON file. Validates first; optional --strict to fail on validation warnings.
aio ffcpe catalog inspect ACTIONTYPE	GET one action; optional --version for a specific semver.
aio ffcpe catalog list	GET catalog actions (supports filters per command help).
aio ffcpe catalog update ACTIONTYPE	PUT a full replacement definition.
aio ffcpe catalog disable ACTIONTYPE	Disable (and typically hide from the FFCPE workflow UI).
aio ffcpe catalog enable ACTIONTYPE	Re-enable a disabled action.
aio ffcpe catalog delete ACTIONTYPE	DELETE; use --version to delete one semver only.

Run aio ffcpe catalog --help or aio ffcpe catalog <command> --help for exact flags and examples.

Common flags

• --org-id — override x-gw-ims-org-id (default from aio console org select).
• --api-key — override x-api-key when needed.
• --json — print raw API JSON where supported.

Authoring catalog entries

The CLI does not scaffold entries interactively. Use the ffcpe-catalog-entry-json skill (or /aio-ffcpe-skills:ffcpe-catalog-entry-json when the plugin is installed).

Recommended layout in App Builder repos: store each action’s catalog JSON as <action-name>.entry.json next to <action-name>.web.* and <action-name>.worker.* (e.g. actions/resize-image/resize-image.entry.json). That groups implementation and registration for one custom action. See ffcpe-app-builder-actions in ffcpe-custom-node-sdk.

Then validate and register:

aio ffcpe catalog validate -f ./actions/resize-image/resize-image.entry.json
aio ffcpe catalog register -f ./actions/resize-image/resize-image.entry.json

Pre-registration: wiring the App Builder project

Before registering, the App Builder app must be deployed and the local project wired to a Console workspace.

Console project naming

Rule	Detail
Alphanumeric only	Hyphens rejected: demo-qr-app fails with Project name … is invalid
Max 20 characters	Longer names fail at create time
Name ≠ package	Console project (e.g. demoQrFfcpe) can differ from OpenWhisk runtimeManifest package (e.g. demo-qr-custom-ffcpe-nodes)

Stage and Production workspaces are created automatically with a new project.

Console CLI flag gotchas

The aio console workspace commands have inconsistent flag shapes — using the wrong flag throws NonExistentFlagsError:

Command	Correct flags
aio console workspace create	--projectName <name> (required), --name <name> (required)
aio console workspace select	positional [NAME_OR_ID] + optional --projectId <id>
aio console workspace list	--projectId <id> — no --projectName flag
aio console workspace download	optional positional destination path

Wire, build, deploy

aio console project create -n myproject -t "My FFCPE App" --json
aio console project select myproject
aio console workspace select Stage --projectId <PROJECT_ID>
aio console workspace download myproject-Stage.json
echo 'myproject-Stage.json' >> .gitignore
aio app use myproject-Stage.json --overwrite --no-input
aio app build
aio app deploy

Use --overwrite --no-input on aio app use when .env already exists from aio app init — otherwise the CLI prompts interactively and can hang in agent/CI sessions.

The downloaded JSON file contains client credentials and API keys. The generated .gitignore does not cover this file automatically (it only covers console.json and .env*). Add the exact filename — or the pattern [0-9]*-*-*.json — immediately after download.

Post-deploy: endpoints → catalog → register

1. Copy each web action base URL from deploy output.
2. Set submitEndpoint = {base}/submit, statusEndpoint = {base}/status in <action-name>.entry.json.
3. Set authentication to ims_service_token when using default SDK route auth (see ffcpe-catalog-entry-json).
4. Register:

aio console org select
aio ffcpe catalog validate -f ./actions/my-action/my-action.entry.json
aio ffcpe catalog register -f ./actions/my-action/my-action.entry.json
# or, if actionType already exists:
aio ffcpe catalog update my-action -f ./actions/my-action/my-action.entry.json

See ffcpe-app-builder-actions skill for the full init-bare → deploy → register flow.

Deeper docs

• skills/README.md — agent skills (Claude / commands, Cursor paths, npx skills install).
• .cursor/ffcpe-catalog/SKILL.md — catalog operations via aio ffcpe catalog (same HTTP API under the hood; do not hand-craft curl).