@sylphx/cli

The official CLI for the Sylphx Platform. Deploy and operate your applications across deployment, logs, env vars, domains, managed databases, object storage, monitoring, webhooks, feature flags, and more directly from your terminal.

Full documentation: sylphx.com/docs

Installation

bun add -g @sylphx/cli
# or
npm install -g @sylphx/cli
# or
pnpm add -g @sylphx/cli

Requires Node.js ≥ 20 (or Bun ≥ 1.3). The CLI binary is sylphx; the published package is a single self-contained ESM bundle (@sylphx/management and @sylphx/contract are bundled via tsup noExternal, so there are no workspace peers to resolve on global install).

Quick start

# Authenticate (opens the browser for OAuth device flow)
sylphx login

# Link the current project to a Sylphx app
cd my-project
sylphx link

# Ship it
sylphx deploy

Authentication

The CLI supports four auth paths (ADR-059 + ADR-074):

| Mode | Use case | How | |---|---|---| | OAuth device flow (default) | Interactive dev | sylphx login — browser-backed device flow, 15-min access + 30-day refresh token stored at ~/.sylphx/config.json (0600), auto-refresh built in | | SYLPHX_TOKEN env var | CI / CD / agents | export SYLPHX_TOKEN=svc_... — no login step, no disk write, stateless service-token auth | | Injected OAuth pair | Managed local agent fleets | SYLPHX_ACCESS_TOKEN=eyJ... + SYLPHX_REFRESH_TOKEN=... — imports the pair into the normal refresh chain and uses the cross-process refresh lock | | SYLPHX_TOKEN_FILE secret file | Local agent fleets / mounted secrets | export SYLPHX_TOKEN_FILE=~/.sylphx/agent-token.env — reads a raw service token, SYLPHX_TOKEN=..., or an access+refresh OAuth pair; fails closed when the file is invalid |

Legacy slx_* personal access tokens were eliminated 2026-04-21 (ADR-059 §1.4) and are no longer accepted by the API.

Under ADR-059, OAuth tokens are stored as an atomic { accessToken, refreshToken, expiresAt, refreshExpiresAt } record with mode 0600 on disk. The refresh interceptor (utils/oauth-refresh.ts) transparently rotates the access token when it's within the refresh window. Reuse/expiry clears only the rejected refresh-token chain; refresh transport failures are reported as outages and never silently erase the stored login.

# Interactive (developers)
sylphx login
sylphx whoami        # → "Auth: stored OAuth session (~/.sylphx/config.json)"
sylphx logout

# Non-interactive (CI / agents)
export SYLPHX_TOKEN=svc_…
sylphx whoami        # → "Auth: SYLPHX_TOKEN env var"

export SYLPHX_ACCESS_TOKEN=eyJ…
export SYLPHX_REFRESH_TOKEN=...
sylphx whoami        # → "Auth: SYLPHX_ACCESS_TOKEN/SYLPHX_REFRESH_TOKEN env vars"

printf '%s\n' 'SYLPHX_TOKEN=svc_…' > ~/.sylphx/agent-token.env
chmod 600 ~/.sylphx/agent-token.env
export SYLPHX_TOKEN_FILE=~/.sylphx/agent-token.env
sylphx whoami        # → "Auth: SYLPHX_TOKEN_FILE (...)"

sylphx deploy --env=production
sylphx status --project=proj_abc123 --org=my-org
sylphx logs --project=proj_abc123 --org=my-org --tail=100
sylphx logs --project=proj_abc123 --org=my-org --type=build --tail=100
sylphx env set DATABASE_URL=postgres://... --project=proj_abc123 --org=my-org --secret
sylphx config set PUBLIC_URL=https://app.example.com --project=proj_abc123 --org=my-org
sylphx secrets set --project=proj_abc123 --org=my-org --key STRIPE_SECRET --value sk_live_...
sylphx storage list --project=proj_abc123 --org=my-org
sylphx volumes list --project=proj_abc123 --org=my-org
sylphx resources bind res_abc123 --project=proj_abc123 --org=my-org --env=production
sylphx run-cmd --project=proj_abc123 --org=my-org --env=production -- bun test
sylphx promote --project=proj_abc123 --org=my-org --from=staging --to=production --yes
sylphx releases list --project=proj_abc123 --org=my-org

Non-interactive use (CI / agents)

Set SYLPHX_TOKEN to a svc_* service token for stateless CI, or inject SYLPHX_ACCESS_TOKEN + SYLPHX_REFRESH_TOKEN when a managed credential broker owns an OAuth session. Every CLI command honours the active source:

• SYLPHX_ACCESS_TOKEN + SYLPHX_REFRESH_TOKEN wins first. The CLI writes the pair into ~/.sylphx/config.json, then uses the same proactive/reactive refresh path and cross-process refresh lock as sylphx login. SYLPHX_TOKEN may supply the access token only when SYLPHX_REFRESH_TOKEN is present and the token is not svc_*.
• SYLPHX_TOKEN=svc_... is next and stays stateless: no login step, no browser, no config write.
• SYLPHX_TOKEN_FILE is next in precedence and supports a raw token, SYLPHX_TOKEN=svc_..., export SYLPHX_TOKEN="svc_...", or SYLPHX_ACCESS_TOKEN=... + SYLPHX_REFRESH_TOKEN=....
• If SYLPHX_TOKEN_FILE is set but unreadable or empty, the CLI fails closed instead of silently using a stored human OAuth session.
• The OAuth refresh interceptor is skipped only for stateless service token sources. Access-token-only OAuth JWTs are short-lived and should be paired with SYLPHX_REFRESH_TOKEN or replaced by a service token.
• Empty string (SYLPHX_TOKEN=) is treated as unset and falls back to the stored session — defends against misconfigured CI shell exports.
• The same SYLPHX_TOKEN GitHub Actions output minted by sylphx ci github-actions is the variable the CLI itself consumes. One contract, no shell glue.

GitHub Actions example:

- run: sylphx deploy --env=production
  env:
    SYLPHX_TOKEN: ${{ secrets.SYLPHX_TOKEN }}

Local agent example:

install -m 700 -d ~/.sylphx
printf '%s\n' 'SYLPHX_TOKEN=svc_...' > ~/.sylphx/agent-token.env
chmod 600 ~/.sylphx/agent-token.env
export SYLPHX_TOKEN_FILE=~/.sylphx/agent-token.env
sylphx doctor

Agents should prefer a scope-limited svc_* service token for long-running automation. If a broker injects OAuth, inject both access and refresh tokens so the CLI can rotate the chain. Do not copy ~/.sylphx/config.json between machines: the OAuth refresh token is single-use rotation state.

Configuration

Stored at ~/.sylphx/config.json:

{
  "oauth": {
    "accessToken": "eyJ...",
    "refreshToken": "ref_...",
    "expiresAt": "2026-04-23T15:00:00.000Z",
    "refreshExpiresAt": "2026-05-23T15:00:00.000Z"
  },
  "defaultOrg": "org_xyz789"
}

Repo project binding and deployment intent live in ./sylphx.toml (git-committable):

version = "1"

[project]
id = "proj_abc123"
name = "My Project"
slug = "my-project"
org_id = "org_xyz789"
org = "my-org"
default_env = "production"

The home config is private operator state only. It does not store per-directory project links.

Environment variables

| Variable | Description | |---|---| | SYLPHX_TOKEN | Stateless bearer token for non-interactive auth (CI / agents). Use svc_* service tokens. Empty string is treated as unset. | | SYLPHX_ACCESS_TOKEN | OAuth access token for managed agents. Must be paired with SYLPHX_REFRESH_TOKEN; wins over stateless SYLPHX_TOKEN and participates in CLI refresh. | | SYLPHX_REFRESH_TOKEN | OAuth refresh token for managed agents. Used only with SYLPHX_ACCESS_TOKEN or a non-service-token SYLPHX_TOKEN. | | SYLPHX_TOKEN_FILE | Path to a non-interactive auth secret file. Accepts a raw service token, SYLPHX_TOKEN=..., export SYLPHX_TOKEN="...", or SYLPHX_ACCESS_TOKEN=... + SYLPHX_REFRESH_TOKEN=.... Fails closed when set but invalid. | | SYLPHX_CONFIG_DIR | Advanced automation override for the CLI config directory. Use in CI, tests, and hermetic agent sandboxes to avoid reading or writing the operator's real ~/.sylphx credentials. | | SYLPHX_API_URL | Override API base URL (default: https://sylphx.com) |

Commands

Authentication & identity

| Command | Purpose | |---|---| | sylphx login | OAuth device flow — browser-based, stores access + refresh tokens | | sylphx logout | Clear stored credentials | | sylphx whoami | Show current user + org + linked project |

Project lifecycle

| Command | Purpose | |---|---| | sylphx init | Scaffold a new project | | sylphx link | Link current directory to a Sylphx app | | sylphx unlink | Remove the project link | | sylphx open | Open the linked project, or an explicit project with --project/--org | | sylphx projects | List / manage projects | | sylphx orgs | List / switch organizations |

Deployment

| Command | Purpose | |---|---| | sylphx deploy | Deploy the linked project, or an explicit project with --project/--org; verifies final state from the deployment record if the build-log stream drops | | sylphx deployments | List / inspect deployments | | sylphx releases | Browse release history for a linked or explicit project | | sylphx inspect | Inspect a deployment's build + run metadata | | sylphx bisect | Git-bisect-style regression hunt across deployments for a linked or explicit project | | sylphx promote | Promote one environment into another for a linked or explicit project | | sylphx rollback | Roll back a linked or explicit project deployment | | sylphx status | Deployment + health status for a linked or explicit project | | sylphx logs | Inspect bounded runtime logs for a linked or explicit project; add --follow for SSE or --type=build for deploy logs | | sylphx tail | Follow runtime logs with structured formatting; accepts the same filters as logs | | sylphx run-cmd | Run a local command with remote env from a linked or explicit project |

Managed primitives

| Command | Purpose | |---|---| | sylphx db | Manage PostgreSQL databases (CNPG-backed) | | sylphx storage | Manage object storage buckets for a linked or explicit project (Ceph S3) | | sylphx volumes | Manage persistent volumes for a linked or explicit project (Rook-Ceph RWO/RWX) | | sylphx resources | Bind / unbind shared resources for a linked or explicit project | | sylphx services | List + deploy service blueprints | | sylphx config | Per-environment app config for a linked or explicit project | | sylphx env | Environment variables and environments for a linked or explicit project | | sylphx secrets | Encrypted project secrets for a linked or explicit project | | sylphx tasks | Task definitions (job / cron / service) for a linked or explicit project | | sylphx domains | Custom domains + TLS for a linked or explicit project | | sylphx sandbox | Interactive sandbox environments for a linked or explicit project | | sylphx runners | Self-hosted runner admin |

Integration primitives

| Command | Purpose | |---|---| | sylphx backup | Managed data backup + restore | | sylphx webhooks | Outbound webhook endpoint CRUD | | sylphx flags | Feature flag admin | | sylphx secrets | Secret management (AES-256-GCM at rest) | | sylphx realtime | Realtime channel admin | | sylphx saml | SAML SSO configuration | | sylphx ai | AI model / completion admin | | sylphx session-replay | Session replay admin | | sylphx search | Search index admin | | sylphx engagement | Engagement campaign admin | | sylphx consent | GDPR / CCPA consent admin | | sylphx privacy | Privacy / data-subject-request admin | | sylphx referrals | Referral program admin | | sylphx newsletter | Newsletter admin |

Billing & scale

| Command | Purpose | |---|---| | sylphx plan | View / upgrade plan for a linked or explicit project | | sylphx billing | Invoices, payment methods | | sylphx experiments | A/B experiment admin | | sylphx analytics | Analytics admin queries |

Observability & integrations

| Command | Purpose | |---|---| | sylphx monitoring | Metric + alert admin | | sylphx certs | TLS certificate inspection | | sylphx email | Transactional email admin | | sylphx notifications | Push / in-app notification admin |

Machine identity & policy

| Command | Purpose | |---|---| | sylphx tokens | Service token issuance + revocation | | sylphx oidc | OIDC federation (GitHub Actions, GitLab CI, …) | | sylphx ci | CI integration helpers (generates workflow snippets) |

Architecture

• Built on @effect/cli (ADR-073 Strategy A) — every command is an Effect value, tests can swap the Layer and assert on the Exit channel without subprocessing.
• BunRuntime.runMain is the single runPromise-like call site (ADR-058 Rule 21).
• Management plane only (ADR-083) — runtime BaaS verbs (kv.*, email.send, flags.evaluate, …) live inside the deployed application via @sylphx/sdk.
• Types derive from @sylphx/contract (Effect Schema SSOT, ADR-084). Hand-written wire types are a bug.
• HTTP client is @sylphx/management bundled in via tsup noExternal — global install has zero workspace peers to resolve.

Version compatibility

| CLI | Management API | Contract | |---|---|---| | @sylphx/[email protected] (beta) | api.sylphx.com/v1 | @sylphx/contract (workspace / beta) |

The Management API /v1 surface is the stable HTTP target per ADR-077; the CLI and SDK packages themselves are still in pre-1.0 beta. The CLI auto-detects API version and degrades gracefully on newer fields.

Development

bun install
bun run dev -- --help     # Run CLI against workspace
bun run build             # Build production bundle via tsup
bun test                  # Run test suite (bun test)

Related packages

• @sylphx/management — Promise SDK the CLI is built on (bundled).
• @sylphx/contract — Effect Schema SSOT (bundled).
• @sylphx/sdk — runtime BaaS SDK for deployed apps.

License

MIT — see LICENSE.