Felan CLI

felan-ai/felan-cli is the public repository for the Felan command-line interface, installable agent skill, and reusable Node.js client. It manages Felan cloud team sessions and team configuration through the public v1 API, with secure credential resolution, stable machine output, and structured API errors.

The package is ESM-only, requires Node.js 22.19.0 or newer, and has no runtime dependencies. Builds and release automation use Node.js 22.20.0 from .node-version.

Install

Install a published release globally:

npm install -g @felan-ai/cli
felan-cli --help

Or run a published release without installing it:

npx @felan-ai/cli --help
npx @felan-ai/cli sessions list --json

The package must be available on npm for either command. For source development before or between releases, follow Development.

Install the agent skill

Install the felan skill into a supported local coding agent from the public GitHub repository:

npx skills add felan-ai/felan-cli --skill felan

List or install it from a local checkout:

npx skills add ./ --list
npx skills add ./ --skill felan

The skill is at skills/felan/SKILL.md. It gives local coding agents progressive instructions for deciding when to delegate work, writing complete objectives, managing configuration, monitoring asynchronous sessions, parsing output, and handling the cloud/local boundary safely.

Commands

felan-cli --help
felan-cli --version
felan-cli config show [--json|--ndjson]
felan-cli config get <api-key|team-slug|api-url> [--json|--ndjson]
felan-cli config set <api-key|team-slug|api-url> <value> [--json|--ndjson]
felan-cli config unset <api-key|team-slug|api-url> [--json|--ndjson]

felan-cli team get
felan-cli integrations list [--providers <comma-separated>]

felan-cli environments list
felan-cli environments create --name <name> [--slug <slug>] [--description <text>] [--default]

felan-cli env-vars list [--environment <slug>] [--environment-id <uuid>]
felan-cli env-vars set <name> --value <value> [--secret|--no-secret] [--source <source>] [selectors] [--metadata <json>]
felan-cli env-vars update <name> [--value <value>] [--secret|--no-secret] [--source <source>] [selectors] [--metadata <json>]
felan-cli env-vars delete <name> [selectors]

felan-cli automations list
felan-cli automations get <automationId>
felan-cli automations create [--file <path>|--data <json>]
felan-cli automations update <automationId> [--file <path>|--data <json>]
felan-cli automations delete <automationId>

felan-cli events send [--file <path>|--data <json>]

felan-cli sessions start [--prompt <text>] [--watch]
felan-cli sessions list [--status <status>] [--limit <n>]
felan-cli sessions get <sessionId>
felan-cli sessions send <sessionId> [--message <text>]
felan-cli sessions steer <sessionId> --message <text>
felan-cli sessions kill <sessionId>
felan-cli sessions transcript <sessionId> [--after-sequence <cursor>] [--limit <n>] [--follow]
felan-cli sessions watch <sessionId>

Selectors are --environment <slug> and --environment-id <uuid>. When both are supplied, the API gives the environment ID precedence.

Every command accepts these global options in addition to the environment and file configuration described below:

--api-key <key>
--team-slug <slug>
--api-url <url>
--json
--ndjson

Configuration is stored only when config set or config unset changes an existing file. Ordinary reads do not create files. The default path is:

• $XDG_CONFIG_HOME/felan/config.json when XDG_CONFIG_HOME is set
• ~/.config/felan/config.json otherwise

Writes set the felan directory to mode 0700 and config.json to mode 0600.

Environment and precedence

| Variable | Purpose | | --- | --- | | FELAN_API_KEY | Felan team API key sent as a Bearer token | | FELAN_TEAM_SLUG | Team slug used by resource commands | | FELAN_API_URL | API base URL; defaults to https://app.felan.ai/api/v1 | | FELAN_POLL_INTERVAL_MS | Poll interval for session watch/follow; defaults to 2000 |

Resolved configuration uses this deterministic order, from highest to lowest priority:

1. Global CLI flags (--api-key, --team-slug, and --api-url)
2. Environment variables
3. User config file

For example:

export FELAN_API_KEY="your-team-api-key"
export FELAN_TEAM_SLUG="your-team-slug"
felan-cli team get

The team slug appears in dashboard URLs and as a read-only value under Team Settings → General Settings.

API key safety

Use placeholders in examples and shell history:

export FELAN_API_KEY="your-team-api-key"
felan-cli config set api-key "your-team-api-key"

The CLI never prints a complete API key. config get api-key and config show redact it to a short prefix and final four characters, or to <redacted> for short values. The API client does not log requests, headers, or credentials.

Environment-variable values are also suppressed from command output. Pass a sensitive value through stdin to keep it out of shell history:

printf '%s' "$TOKEN" | felan-cli env-vars set TOKEN --value - --secret --environment production

Team configuration examples

felan-cli integrations list --providers github,linear
felan-cli environments create --name Production --slug production --default
felan-cli env-vars list --environment production --json
felan-cli env-vars update LOG_LEVEL --value debug --no-secret --environment production
felan-cli env-vars delete RETIRED_TOKEN --environment production

Environment creation also accepts a JSON object with --file, --data, or stdin. Automation create/update and event send accept a JSON object from --file <path>, inline --data '<json>', --file -, or piped stdin:

felan-cli automations create --file automation.json
felan-cli automations update 00000000-0000-0000-0000-000000000000 --data '{"status":"paused"}'
printf '%s' '{"event_type":"deployment.completed","data":{"environment":"production"}}' \
  | felan-cli events send

--json emits a stable { "data": ..., "meta": { "rateLimit": ..., "status": ... } } envelope. For list commands, --ndjson emits one stable envelope per resource. Errors in either machine format are written to stderr as { "error": { "code": ..., "message": ..., "status"?: ..., "rateLimit"?: ... } }.

Cloud sessions

Start work and return the accepted session immediately:

felan-cli sessions start --prompt "Review the open change and run the relevant checks."
printf '%s' "Review the open change" | felan-cli sessions start

Add --watch, or use felan-cli sessions watch <sessionId>, to poll status, direct child lifecycle changes, and newly appended transcript events until the root session is terminal. A completed root exits successfully. failed, timed_out, and cancelled roots use distinct non-zero exit codes.

felan-cli sessions list --status running --limit 25
felan-cli sessions get 00000000-0000-0000-0000-000000000000
felan-cli sessions transcript 00000000-0000-0000-0000-000000000000 --follow
felan-cli sessions send 00000000-0000-0000-0000-000000000000 --message "Continue with the fixes."
felan-cli sessions steer 00000000-0000-0000-0000-000000000000 --message "Focus on the failing tests."
felan-cli sessions kill 00000000-0000-0000-0000-000000000000

sessions start --prompt -, an omitted start prompt, and an omitted sessions send --message read text from piped stdin. Transcript sequences, --after-sequence, and returned cursors remain decimal strings.

Use sessions send for a follow-up in the session conversation. Use sessions steer to redirect a currently running session in flight; the API rejects steering a session that is not running. Both actions are accepted asynchronously, so inspect or watch the session for the resulting state.

sessions get includes direct child sessions in data.children. Transcript pages include events, next_cursor, and has_more:

felan-cli sessions get "$SESSION_ID" --json | jq '.data.children[] | {id,status,title}'
page=$(felan-cli sessions transcript "$SESSION_ID" --limit 1000 --json)
cursor=$(printf '%s\n' "$page" | jq -r '.data.next_cursor // empty')
felan-cli sessions transcript "$SESSION_ID" --after-sequence "$cursor" --follow --ndjson

Watch and follow preserve the last transcript cursor and retry network failures, HTTP 429, and HTTP 5xx responses after FELAN_POLL_INTERVAL_MS. Other API errors return immediately. Pressing Ctrl-C stops local polling with exit 11; use sessions kill to request remote cancellation.

Sessions use Supabase-backed Felan state and managed agent-runtime workspaces. They operate on Felan-configured resources and remote repository state; prepare required changes in a remote branch or revision before delegation. Sessions inherit team Private Connectivity configured in the Felan dashboard.

For finite session commands, --json and --ndjson use the same stable response envelopes as other commands. Streaming watch/follow commands emit one stable JSON object per line with --json or --ndjson:

• session_status records contain session_id, status, and previous_status
• child_status records contain session_id, child, and previous_status
• transcript_event records contain session_id and event

The CLI prints any session/dashboard path included in API data and does not synthesize a dashboard URL.

For finite list commands, NDJSON records retain the finite response envelope:

{"data":{"id":"session-id"},"meta":{"rateLimit":{},"status":200}}

Streaming records do not use that envelope:

{"type":"session_status","session_id":"session-id","status":"running","previous_status":"pending"}

Exit codes

| Code | Meaning | | ---: | --- | | 0 | Success, including a completed watched session | | 1 | Unexpected CLI error | | 2 | Invalid command usage | | 3 | Authentication or authorization failure | | 4 | Resource not found | | 5 | API rate limit | | 6 | API error | | 7 | Missing or invalid configuration | | 8 | Network/transport error | | 9 | Watched session failed | | 10 | Watched session timed out | | 11 | Watched session or local operation cancelled |

Library API

The package exports reusable ESM modules from the package root and subpaths including @felan-ai/cli/api-client, @felan-ai/cli/config, @felan-ai/cli/errors, @felan-ai/cli/output, and @felan-ai/cli/types.

The fetch-based API client:

• encodes every path segment and query value safely
• sends Authorization: Bearer <team-key>
• parses { "data": ... } success and { "error": { "code": ..., "message": ... } } failure envelopes
• supports 204 No Content
• provides get, post, put, patch, and delete helpers
• exposes response headers and typed rate-limit metadata on both successful responses and API errors

Development

pnpm install
pnpm build
node dist/cli.js --help
pnpm type-check
pnpm lint
pnpm test
pnpm pack:check
npx skills add ./ --list

Tests use Node's built-in test runner, mocked fetch, and temporary directories. They do not access the live Felan API or the user's home directory. The packed-install test creates the real npm tarball, installs it without npm credentials in clean temporary projects, executes its installed felan-cli binary, and verifies co-installation with @felan-ai/[email protected] and its separate felan binary.

To exercise local skill installation without changing an existing project, create a temporary project and point skills at this checkout:

repo=$PWD
target=$(mktemp -d)
cd "$target"
git init -q
npx skills add "$repo" --skill felan --agent codex --copy --yes
npx skills list --agent codex

Publishing

The package publishes from .github/workflows/release.yml through npm trusted publishing with OIDC and provenance. Stable v<version> tags must match package.json, point to a commit on main, and name an unpublished npm version. Before creating a release tag, update the package and skill versions together, update the changelog, and run every development check. The workflow repeats those checks on Node.js 22.20.0 before publishing.

Configure the npm trusted publisher for organization felan-ai, repository felan-cli, workflow release.yml, and environment npm. The workflow uses no long-lived npm publish token. The package file whitelist permits skills and docs alongside the built dist output, MIT license, changelog, and build instructions.

License

MIT