Adobe 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_URLor 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— overridex-gw-ims-org-id(default fromaio console org select).--api-key— overridex-api-keywhen 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
- Copy each web action base URL from deploy output.
- Set
submitEndpoint={base}/submit,statusEndpoint={base}/statusin<action-name>.entry.json. - Set
authenticationtoims_service_tokenwhen using default SDK route auth (seeffcpe-catalog-entry-json). - 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 skillsinstall)..cursor/ffcpe-catalog/SKILL.md— catalog operations viaaio ffcpe catalog(same HTTP API under the hood; do not hand-craft curl).