CLI

Discover the catalogue for an API key, then deploy defineWorkflow, defineAgent, and defineEntityType definitions.

The @lunnoa/client CLI does two jobs: discover what a key can see, and deploy local define* files so they appear in Automate. Prefer the CLI for both. Thin SDK upsert helpers exist as an implementation detail.

Auth is the same everywhere: --url / LUNNOA_URL, --api-key / LUNNOA_API_KEY, optional --access-token, and --project-id / LUNNOA_PROJECT_ID where a project is required. Optional lunnoa.config.ts (or .mjs / .js / .json) in the working directory can supply the same values. Use --json when a coding agent is reading the output.

Discover

tools list is compact. tools get prints inputConfig, field summaries, and a defineAction({ id, appId, input }) sketch. --for-agent keeps only catalogue entries marked availableForAgent. --app scopes tools and connections to one workflow app.

discover.sh

npx @lunnoa/client tools list --for-agent --jsonnpx @lunnoa/client tools search email --for-agent --jsonnpx @lunnoa/client tools get http_action_send-request --jsonnpx @lunnoa/client tools get http.http_action_send-request --jsonnpx @lunnoa/client apps list --jsonnpx @lunnoa/client apps get http --jsonnpx @lunnoa/client connections list --app gmail --jsonnpx @lunnoa/client connections get <connection-uuid> --jsonnpx @lunnoa/client agents list --jsonnpx @lunnoa/client workflows list --jsonnpx @lunnoa/client entity-types list --jsonnpx @lunnoa/client projects list --jsonnpx @lunnoa/client features --json

Typical coding-agent loop: tools list or tools search → tools get for the schema → write defineAction → deploy. connections list supplies the Connection instance UUID when a tool needsConnection. projects list supplies --project-id for workflow and agent deploy.

There is no actions run CLI command. Run catalogue actions from code (actions.run / runs.start). See Run actions and Discovery.

Deploy

Definition	Upsert key	Scope	CLI
`defineWorkflow`	project-scoped `slug`	Project	`workflows deploy`
`defineAgent`	project-scoped `slug`	Project	`agents deploy`
`defineEntityType`	workspace-scoped `slug`	Workspace	`entity-types deploy`

deploy.sh

npx @lunnoa/client workflows deploy ./workflows/sync-orders.ts \  --url https://lunnoa.example \  --api-key "$LUNNOA_API_KEY" \  --project-id "$LUNNOA_PROJECT_ID"npx @lunnoa/client agents deploy ./agents/triage.ts \  --url https://lunnoa.example \  --api-key "$LUNNOA_API_KEY" \  --project-id "$LUNNOA_PROJECT_ID"npx @lunnoa/client entity-types deploy ./types/invoice.ts \  --url https://lunnoa.example \  --api-key "$LUNNOA_API_KEY"

You can also list what is already deployed: workflows list, agents list, entity-types list. Redeploying the same slug updates the row and keeps managedByCode: true.

For TypeScript definition files, run under Node with --experimental-strip-types (Node ≥ 22) or use tsx.

Definition file shape

Export defineWorkflow(…), defineAgent(…), or defineEntityType(…) as default, or as workflow / agent / entityType. Nested defineWorkflow tools on an agent are deployed first, then linked via workflowIds.

What gets written

Real Workflow / Agent / ObjectType rows (visible in Automate)
slug + managedByCode set for code-managed identity
Workflow graph: manual trigger → linear catalogue-action steps
Entity types: attributeSchema / optional stateSchema, schemaRevision bumped on schema changes, allowUnknownAttributes default false