CLI Commands¶

Coming Soon

The flow-sdk CLI is not yet publicly available. It will be released in an upcoming release. The documentation below is provided as a preview of upcoming capabilities. Today, the SDK is available inside Code Blocks, Hosted Services, Agents, and Workflows on the Manifest Platform — no installation required.

The flow-sdk CLI is namespace-first. Use grouped commands for authentication, development, deployments, service invocation, and platform CRUD operations.

Command Groups¶

flow-sdk --help

Root groups:

auth - authentication and identity
dev - local component development workflows
deployments - deploy/publish/promote/rollback/list/status
services - hosted service invocation
components, connectors, datasets, hosted-services, solutions, policies, webhooks, mcp-servers, experiments - canonical management CRUD namespaces

`flow-sdk auth login`¶

Authenticate with the Manifest Platform and store credentials locally.

flow-sdk auth login --api-key <api-key> --url <platform-url>

How It Works¶

Exchanges your organization API key (fl_...) for a JWT access token
Auto-discovers accessible organizations and workspaces
Stores the token and tenant context in ~/.flow/config.json (permissions 0600)

Options¶

Flag	Required	Description
`--api-key`	Yes	Organization API key (prompted securely if omitted)
`--url`	Yes	Platform API URL (prompted if omitted)
`--org-id`	No	Organization UUID (auto-discovered if omitted)
`--workspace-id`	No	Workspace UUID (auto-discovered if omitted)

Examples¶

InteractiveNon-InteractiveExplicit Tenant

flow-sdk auth login
# Prompts for API key (hidden) and URL
# Auto-selects organization and workspace

flow-sdk auth login \
  --api-key fl_your_api_key \
  --url https://api.flow.marut.cloud

flow-sdk auth login \
  --api-key fl_your_api_key \
  --url https://api.flow.marut.cloud \
  --org-id 550e8400-e29b-41d4-a716-446655440000 \
  --workspace-id 6ba7b810-9dad-11d1-80b4-00c04fd430c8

Output¶

Auto-selected organization: Acme Corp
Auto-selected workspace: Production
Logged in. org=550e8400-... workspace=6ba7b810-...
Credentials saved to ~/.flow/config.json

Multiple Organizations

If your API key has access to multiple organizations, the CLI presents a numbered list for you to choose from.

`flow-sdk auth login-user`¶

Authenticate as a user via request-bound browser flow and pasted token.

flow-sdk auth login-user --url <platform-url> [--token <jwt>]

How It Works¶

CLI creates a one-time request with POST /api/v1/auth/cli-login-requests.
CLI prints a verification URL in the web app (/cli-login/{request_id}?secret=...).
User signs in through the app session (including MFA policy if required), generates token, and pastes it into CLI.
CLI validates token with /auth/me and persists local config.

Options¶

Flag	Required	Description
`--url`	Yes	Platform API URL
`--token`	No	Pre-generated token from request-bound app page

Example¶

flow-sdk auth login-user --url https://api.flow.marut.cloud

`flow-sdk dev scaffold`¶

Generate a new component project with the correct directory structure, imports, configuration files, and test stubs.

flow-sdk dev scaffold <component-name> [--template <template>] [--out <directory>]

Templates¶

Template	Description
`basic`	Minimal component -- implement `execute()` and you are done
`connector`	API-backed component with auth, httpx client lifecycle, and operation stub
`agent`	Pydantic AI agent with tool registration and GatewayClient for LLM calls
`workflow`	Multi-step workflow with node definitions and workflow YAML spec

Options¶

Flag	Default	Description
`--template`, `-t`	`basic`	Project template to use
`--out`, `-o`	`.` (current dir)	Parent directory for the new project
`--list`, `-l`		List available templates and exit

Examples¶

Basic ComponentAgentWorkflowList Templates

flow-sdk dev scaffold my-processor
# Creates ./my-processor/ with basic template

flow-sdk dev scaffold customer-support-agent --template agent
# Creates ./customer-support-agent/ with agent template

flow-sdk dev scaffold etl-pipeline --template workflow --out ./projects
# Creates ./projects/etl-pipeline/ with workflow template

flow-sdk dev scaffold --list

Available templates:

  basic        Minimal component — implement execute() and you are done.
  connector    Adds auth via SecretsClient, httpx client lifecycle, and
               an operation stub for API-backed components.
  agent        Pydantic AI agent with tool registration and GatewayClient
               for LLM calls.
  workflow     Multi-step workflow with node definitions and workflow YAML
               spec.

Usage: flow-sdk dev scaffold <name> --template <template>

Next Steps After Scaffolding¶

cd my-processor
pytest tests/ -v

Naming Rules¶

Component names must:

Start with a letter
Contain only letters, digits, hyphens (-), and underscores (_)
Not include path separators, dots, or spaces

`flow-sdk deployments deploy`¶

Deploy a component to the Manifest Platform.

flow-sdk deployments deploy <path> [--ring <ring>] [--json]

Options¶

Flag	Default	Description
`--ring`	`dev`	Deployment ring: `dev`, `staging`, or `prod`
`--json`		Emit machine-readable JSON output

Examples¶

Deploy to DevDeploy to StagingDeploy to Prod (JSON output)

flow-sdk deployments deploy ./my-processor

flow-sdk deployments deploy ./my-processor --ring staging

flow-sdk deployments deploy ./my-processor --ring prod --json

Prerequisites

You must be logged in (flow-sdk auth login or flow-sdk auth login-user) before deploying. The component directory must contain a valid component.py and any required configuration files.

`flow-sdk deployments publish`¶

Validate and publish a component to the platform catalog.

flow-sdk deployments publish <path> [--json]

Options¶

Flag	Description
`--json`	Emit machine-readable JSON output

Examples¶

# Publish from the component directory
flow-sdk deployments publish ./my-processor

# Machine-readable output for CI/CD
flow-sdk deployments publish ./my-processor --json

`flow-sdk dev test`¶

Run a component through its full lifecycle with a mock runtime context.

flow-sdk dev test <path> [--input <json-file>] [--env <environment>] [--json]

Options¶

Flag	Default	Description
`--input`, `-i`	None	JSON file containing input data for the component
`--env`	`dev`	Simulated environment: `dev`, `staging`, or `prod`
`--json`		Emit machine-readable JSON output

Examples¶

Basic TestWith Input DataJSON Output (CI)

flow-sdk dev test ./my-processor

# Create input.json
echo '{"url": "https://example.com"}' > input.json

flow-sdk dev test ./my-processor --input input.json

flow-sdk dev test ./my-processor --json

Output¶

Component: MyProcessor
  Path:        /Users/you/projects/my-processor
  Environment: dev

Running lifecycle...

Result: SUCCESS (142.3ms)
Output: {"processed": true, "items": 42}

`flow-sdk dev validate`¶

Validate a component's implementation against the platform contract without executing it.

flow-sdk dev validate <path> [--json]

Checks Performed¶

Check	Description
`subclasses_base_component`	Component class extends `BaseComponent`
`execute_is_implemented`	`execute()` method is defined
`models_are_valid_pydantic`	Input/output models are valid Pydantic models
`health_check_returns_valid_result`	`health_check()` returns a `HealthCheckResult`

Examples¶

flow-sdk dev validate ./my-processor

Validating component at: /Users/you/projects/my-processor

  v  subclasses_base_component              OK
  v  execute_is_implemented                 OK
  v  models_are_valid_pydantic              OK
  v  health_check_returns_valid_result      OK

Validation: PASSED (4/4 checks passed)

`flow-sdk auth whoami`¶

Show the current authenticated identity, organization, and workspace.

flow-sdk auth whoami [--json]

Options¶

Flag	Description
`--json`	Emit machine-readable JSON output

Examples¶

Human-ReadableJSON Output

flow-sdk auth whoami

Platform:    https://api.flow.marut.cloud
Auth:        Organization API Key
Org:         Acme Corp (550e8400-...)
Workspace:   Production (6ba7b810-...)
Permissions: 12 scopes

flow-sdk auth whoami --json

`flow-sdk services invoke`¶

Invoke a deployed service endpoint.

flow-sdk services invoke --service-id <uuid> --path <endpoint> [--method <method>] [--body <json>] [--version <n>] [--json]

Options¶

Flag	Default	Description
`--service-id`	(required)	Service UUID to invoke
`--path`	(required)	Endpoint path (e.g. `/analyze`)
`--method`	`POST`	HTTP method (`GET`, `POST`, `PUT`, `DELETE`)
`--body`	None	JSON request body string
`--version`	None	Service version number
`--json`		Emit machine-readable JSON output

Examples¶

POST RequestGET RequestVersioned Endpoint

flow-sdk services invoke \
  --service-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --method POST \
  --path /analyze \
  --body '{"text": "hello"}'

flow-sdk services invoke \
  --service-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --method GET \
  --path /health

flow-sdk services invoke \
  --service-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --method POST \
  --path /process \
  --version 2 \
  --json

Deployment Commands¶

`flow-sdk deployments list`¶

List deployments in the current workspace.

flow-sdk deployments list [--ring <ring>] [--status <status>] [--json]

Flag	Description
`--ring`	Filter by ring name (e.g. `dev`, `staging`, `prod`)
`--status`	Filter by status (e.g. `active`, `failed`)
`--json`	Emit machine-readable JSON output

Examples¶

# List all deployments
flow-sdk deployments list

# Filter by ring and status
flow-sdk deployments list --ring dev --status active --json

`flow-sdk deployments status`¶

Check deployment health and status.

flow-sdk deployments status <deployment-id> [--json]

Examples¶

flow-sdk deployments status d-abc123

flow-sdk deployments status d-abc123 --json

`flow-sdk deployments promote`¶

Promote a deployment to the next ring.

flow-sdk deployments promote <deployment-id> --target-ring <ring> [--notes <text>] [--json]

Flag	Description
`--target-ring`	(required) Target ring ID or name
`--notes`	Optional promotion notes
`--json`	Emit machine-readable JSON output

Examples¶

# Promote to staging
flow-sdk deployments promote d-abc123 --target-ring staging --notes "Release 2.1"

# Promote with JSON output
flow-sdk deployments promote d-abc123 --target-ring production --json

`flow-sdk deployments rollback`¶

Roll back a deployment.

flow-sdk deployments rollback <deployment-id> --reason <text> [--rollback-to <deployment-id>] [--json]

Flag	Description
`--reason`	(required) Reason for rollback
`--rollback-to`	Specific deployment ID to roll back to
`--json`	Emit machine-readable JSON output

Examples¶

# Roll back to previous deployment
flow-sdk deployments rollback d-abc123 --reason "Performance regression"

# Roll back to a specific version
flow-sdk deployments rollback d-abc123 --rollback-to d-xyz789 --reason "Reverting to v1.3"

Hosted Service Token Commands¶

`flow-sdk hosted-services mint-token`¶

Mint an HSL service token for programmatic access to a deployed service.

flow-sdk hosted-services mint-token \
  --service-id <uuid> \
  --claims '{"tenant_id": "t-123", "role": "reader"}' \
  --ttl 120

Flag	Default	Description
`--service-id`	(required)	Hosted service ID
`--claims`	(required)	JSON string of custom claims
`--ttl`	`60`	Token TTL in minutes
`--json`		Emit JSON output

`flow-sdk hosted-services revoke-token`¶

Revoke a single service token by its JTI.

flow-sdk hosted-services revoke-token \
  --service-id <uuid> \
  --jti <token-jti> \
  --expires-at 2025-12-31T23:59:59Z \
  --reason "Credential rotation"

`flow-sdk hosted-services revoke-all-tokens`¶

Revoke all service tokens for a service. Prompts for confirmation unless --yes is passed.

flow-sdk hosted-services revoke-all-tokens \
  --service-id <uuid> \
  --reason "Security incident" \
  --yes

`flow-sdk hosted-services list-revocations`¶

List token revocations for a service.

flow-sdk hosted-services list-revocations --service-id <uuid>
flow-sdk hosted-services list-revocations --service-id <uuid> --include-expired --json

`flow-sdk components backup`¶

Download a platform-admin component backup archive (.tar.gz).

flow-sdk components backup \
  --components all \
  [--component-ids <id1,id2>] \
  [--include-archived] \
  [--output ./components-backup.tar.gz] \
  [--json]

Notes:

Uses canonical endpoint POST /api/v1/orgs/{org_id}/workspaces/{workspace_id}/component-backups/download.
--components accepts all or comma-separated component types (for example agent,codeblock).
Requires platform-admin persona.

Configuration File¶

All CLI commands that interact with the platform read credentials from ~/.flow/config.json:

{
  "access_token": "eyJhbGciOi...",
  "platform_url": "https://api.flow.marut.cloud",
  "org_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

Security

The config file contains a JWT access token and is written with 0600 permissions (owner read/write only). Do not commit this file to version control.

CLI Commands¶

Command Groups¶

flow-sdk auth login¶

How It Works¶

Options¶

Examples¶

Output¶

flow-sdk auth login-user¶

How It Works¶

Options¶

Example¶

flow-sdk dev scaffold¶

Templates¶

Options¶

Examples¶

Next Steps After Scaffolding¶

Naming Rules¶

flow-sdk deployments deploy¶

Options¶

Examples¶

flow-sdk deployments publish¶

Options¶

Examples¶

flow-sdk dev test¶

Options¶

Examples¶

Output¶

flow-sdk dev validate¶

Checks Performed¶

Examples¶

flow-sdk auth whoami¶

Options¶

Examples¶

flow-sdk services invoke¶

Options¶

Examples¶

Deployment Commands¶

flow-sdk deployments list¶

Examples¶

flow-sdk deployments status¶

Examples¶

flow-sdk deployments promote¶

Examples¶

flow-sdk deployments rollback¶

Examples¶

Hosted Service Token Commands¶

flow-sdk hosted-services mint-token¶

flow-sdk hosted-services revoke-token¶

flow-sdk hosted-services revoke-all-tokens¶

flow-sdk hosted-services list-revocations¶

flow-sdk components backup¶

Configuration File¶

`flow-sdk auth login`¶

`flow-sdk auth login-user`¶

`flow-sdk dev scaffold`¶

`flow-sdk deployments deploy`¶

`flow-sdk deployments publish`¶

`flow-sdk dev test`¶

`flow-sdk dev validate`¶

`flow-sdk auth whoami`¶

`flow-sdk services invoke`¶

`flow-sdk deployments list`¶

`flow-sdk deployments status`¶

`flow-sdk deployments promote`¶

`flow-sdk deployments rollback`¶

`flow-sdk hosted-services mint-token`¶

`flow-sdk hosted-services revoke-token`¶

`flow-sdk hosted-services revoke-all-tokens`¶

`flow-sdk hosted-services list-revocations`¶

`flow-sdk components backup`¶