Install and use the Flowcore CLI

The Flowcore CLI is the main terminal interface for interactive platform work. Use it to authenticate, manage profiles, inspect event streams, preview resource changes, and apply v2 manifests.

Application runtimes should use the SDK or Pathways rather than invoking CLI commands as subprocesses.

Requirements and installation

The CLI requires Node.js 18 or newer and runs on macOS, Linux, and Windows.

Install the package globally:

npm install -g @flowcore/cli

Verify that your shell resolves the expected binary:

flowcore --version
flowcore help
flowcore info

flowcore info displays the CLI version and its data, configuration, and cache directories. This is useful when multiple Node installations or user accounts are present.

Pin the CLI version in CI rather than relying on whichever global version happens to be installed on a runner.

Sign in as a user

Interactive user access uses an OAuth/OIDC browser flow:

flowcore login
flowcore whoami

The CLI opens a browser, receives the callback locally, and stores the resulting session in its configuration directory.

Run whoami before changing resources. It confirms the active identity instead of relying on shell history or memory.

Protect the CLI configuration directory like other credential storage. Do not copy its session files into a repository or container image.

Distinguish user sessions from application keys

CLI login represents a person and is suitable for interactive administration according to that user's permissions.

API keys represent applications or automation. Do not copy a user's bearer token into production code or CI merely because an SDK command needs authentication.

Some legacy and user-oriented operations require bearer authentication, while most current REST and ingestion workflows support API keys. Use the authentication type required by the operation and grant the narrowest permissions possible.

Configure profiles

Profiles keep endpoints and authentication settings separate across environments and installations.

Create or update a named profile with:

flowcore config set --profile development
flowcore config set --profile production

The command can configure platform endpoints, login discovery, client credentials, and callback settings. Managed Flowcore and a dedicated installation may require different values. Obtain those values from the platform administrator rather than copying a public managed endpoint into a private installation.

Inspect the active settings:

flowcore config show --profile development
flowcore config show --profile production

Pass the profile explicitly for sensitive commands:

flowcore whoami --profile production
flowcore diff -f resources.yaml --profile production

Explicit profile selection reduces the chance that a previously active development or production profile is used accidentally.

Keep environment identities visually distinct

Profile names should make the environment obvious, such as:

• acme-development
• acme-staging
• acme-production
• acme-dedicated-eu

Avoid ambiguous names such as default, new, or a developer's initials for shared operational work.

Before an apply or delete, compare the profile, authenticated identity, tenant in the manifest, and intended change ticket.

Discover commands from the installed CLI

The CLI is plugin-based, so available commands can vary with the installed version and bundled plugins.

Use built-in help as the immediate source for flags:

flowcore help
flowcore help stream
flowcore help apply
flowcore help diff
flowcore help delete

This is especially important during Flowcore v2 migration because older documentation may show scenario, strand, GraphQL, or legacy data-core commands that are not the current path for new resources.

Inspect events in the terminal

Use flowcore stream for bounded investigation:

flowcore stream \
  "https://flowcore.io/acme-development/commerce/order.0/order.placed.0.stream" \
  --start 1h \
  --json

The stream URL identifies the tenant, data core, flow type, and event type. Common start values include a relative duration, now, first, or an ISO timestamp.

Useful flags include:

• --start and --end for the time range
• --max for a bounded number of events
• --json for machine-readable output
• --payload to output payloads only
• --live to continue following new activity
• --pageSize to control fetch pages
• --concurrency to control parallel output processing
• --includeSensitiveData when explicitly authorized

Use narrow event paths and small historical ranges first. A wildcard across a high-volume data core can produce a large amount of output.

Use wildcards carefully

The modern stream service can resolve wildcard flow and event patterns. This is useful for discovery but broadens data access and workload.

Before streaming a wildcard in production, confirm:

• Which resources it resolves to
• Whether sensitive event types are included
• Whether the terminal or destination can handle the volume
• Whether logs or shell history retain payloads
• Whether the authenticated user is approved for the scope

Prefer an explicit list of event types for repeatable diagnostics.

Forward events to a development endpoint

The CLI can POST streamed events to an HTTP endpoint:

flowcore stream http \
  "https://flowcore.io/acme-development/commerce/order.0/order.placed.0.stream" \
  --start 10m \
  --destination http://localhost:3000/api/flowcore/events \
  --header 'Authorization: Bearer local-test-secret'

HTTP forwarding is useful for exercising a local handler against controlled history. Configure a timeout and a maximum event count while testing.

Do not use CLI forwarding as an unmanaged production consumer. It lacks the intended lifecycle, persisted state, capacity management, and operational ownership of a Data Pathway.

Protect sensitive output

Terminal output can be copied into scrollback, shell transcripts, CI logs, or support tickets.

Keep includeSensitiveData disabled unless the diagnostic requires it and the environment is approved. Avoid redirecting production payloads into temporary files or third-party paste services.

If you need to identify an event, record the event ID, path, and time bucket. Retrieve protected payload details through an authorized tool only when necessary.

Diagnose a stream that returns no events

Confirm the active profile and identity first:

flowcore config show --profile development
flowcore whoami --profile development

Then verify the exact tenant, data core, flow type, event type, and requested time range. A valid command with the wrong profile or empty time buckets correctly returns no events.

Also check whether the producer successfully ingested events and whether the user can read the selected resource.

Diagnose authentication and endpoint problems

If login does not complete, check browser access, callback-port availability, profile discovery settings, and system time.

If commands reach the wrong installation, inspect the profile endpoints rather than repeatedly logging in.

If one command is unauthorized while another works, verify the command's authentication category and the user's or key's specific permissions. Do not replace a narrow credential with an administrator credential as a permanent workaround.

Update deliberately

The CLI checks for updates periodically, but production workflows should adopt versions intentionally.

Before upgrading:

• Read release notes.
• Test login and profile behavior.
• Validate existing manifests.
• Run diffs in a non-production environment.
• Confirm whether v2 flags or schemas changed.
• Update the pinned CI version together with local contributor guidance.

Continue with Manage Flowcore v2 resource manifests.