@sylphx/cli 0.19.3 → 0.20.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +18 -812
- package/README.md +41 -445
- package/bin/run.js +41 -0
- package/binaries/linux-x64/sylphx +0 -0
- package/install.js +37 -0
- package/lib/get-binary.js +110 -0
- package/lib/index.js +12 -0
- package/lib/platform.js +40 -0
- package/package.json +63 -73
- package/dist/main.d.ts +0 -1
- package/dist/main.js +0 -48572
- package/dist/main.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,466 +1,62 @@
|
|
|
1
|
-
#
|
|
1
|
+
# `@sylphx/cli`
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
[](./LICENSE)
|
|
5
|
-
[](https://www.typescriptlang.org/)
|
|
3
|
+
**npm install channel for the Rust operator CLI** (`sylphx`).
|
|
6
4
|
|
|
7
|
-
|
|
5
|
+
This package does **not** reimplement the CLI in TypeScript. It installs and
|
|
6
|
+
executes the same native binary published as **`sylphx-cli`** on crates.io
|
|
7
|
+
(ADR-3820 sole-wire dual-language product path).
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
| Channel | Command | Product |
|
|
10
|
+
| --- | --- | --- |
|
|
11
|
+
| **npm** | `npm install -g @sylphx/cli` | Rust `sylphx` binary |
|
|
12
|
+
| **crates.io** | `cargo install sylphx-cli` | same Rust `sylphx` binary |
|
|
10
13
|
|
|
11
|
-
##
|
|
14
|
+
## Install
|
|
12
15
|
|
|
13
16
|
```bash
|
|
14
|
-
bun add -g @sylphx/cli
|
|
15
|
-
# or
|
|
16
17
|
npm install -g @sylphx/cli
|
|
17
|
-
#
|
|
18
|
-
|
|
18
|
+
# equivalent:
|
|
19
|
+
cargo install sylphx-cli
|
|
19
20
|
```
|
|
20
21
|
|
|
21
|
-
|
|
22
|
+
Ships a vendored native binary under `binaries/<os>-<arch>/` for supported hosts (linux-x64 first). Optional platform packages (`@sylphx/cli-linux-x64`,
|
|
23
|
+
`@sylphx/cli-darwin-arm64`, …). If the optional native package is missing for
|
|
24
|
+
your OS/arch, install falls back messaging to `cargo install sylphx-cli`.
|
|
22
25
|
|
|
23
|
-
|
|
26
|
+
Override path (advanced):
|
|
24
27
|
|
|
25
28
|
```bash
|
|
26
|
-
|
|
27
|
-
sylphx login
|
|
28
|
-
|
|
29
|
-
# Link the current project to a Sylphx app
|
|
30
|
-
cd my-project
|
|
31
|
-
sylphx link
|
|
32
|
-
|
|
33
|
-
# Ship it
|
|
34
|
-
sylphx deploy
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
## Authentication
|
|
38
|
-
|
|
39
|
-
The CLI supports four auth paths (ADR-059 + ADR-074):
|
|
40
|
-
|
|
41
|
-
| Mode | Use case | How |
|
|
42
|
-
|---|---|---|
|
|
43
|
-
| **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 |
|
|
44
|
-
| **`SYLPHX_TOKEN` env var** | CI / CD / agents | `export SYLPHX_TOKEN=svc_...` — no login step, no disk write, stateless service-token auth |
|
|
45
|
-
| **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 |
|
|
46
|
-
| **`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 |
|
|
47
|
-
|
|
48
|
-
Legacy `slx_*` personal access tokens were eliminated 2026-04-21 (ADR-059 §1.4) and are no longer accepted by the API.
|
|
49
|
-
|
|
50
|
-
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.
|
|
51
|
-
|
|
52
|
-
```bash
|
|
53
|
-
# Interactive (developers)
|
|
54
|
-
sylphx login
|
|
55
|
-
sylphx whoami # → "Auth: stored OAuth session (~/.sylphx/config.json)"
|
|
56
|
-
sylphx logout
|
|
57
|
-
|
|
58
|
-
# Non-interactive (CI / agents)
|
|
59
|
-
export SYLPHX_TOKEN=svc_…
|
|
60
|
-
sylphx whoami # → "Auth: SYLPHX_TOKEN env var"
|
|
61
|
-
|
|
62
|
-
export SYLPHX_ACCESS_TOKEN=eyJ…
|
|
63
|
-
export SYLPHX_REFRESH_TOKEN=...
|
|
64
|
-
sylphx whoami # → "Auth: SYLPHX_ACCESS_TOKEN/SYLPHX_REFRESH_TOKEN env vars"
|
|
65
|
-
|
|
66
|
-
printf '%s\n' 'SYLPHX_TOKEN=svc_…' > ~/.sylphx/agent-token.env
|
|
67
|
-
chmod 600 ~/.sylphx/agent-token.env
|
|
68
|
-
export SYLPHX_TOKEN_FILE=~/.sylphx/agent-token.env
|
|
69
|
-
sylphx whoami # → "Auth: SYLPHX_TOKEN_FILE (...)"
|
|
70
|
-
|
|
71
|
-
sylphx deploy --env=production
|
|
72
|
-
sylphx status --project=proj_abc123 --org=my-org
|
|
73
|
-
sylphx logs --project=proj_abc123 --org=my-org --tail=100
|
|
74
|
-
sylphx logs --project=proj_abc123 --org=my-org --type=build --tail=100
|
|
75
|
-
sylphx env set DATABASE_URL=postgres://... --project=proj_abc123 --org=my-org --secret
|
|
76
|
-
sylphx env set LOKI_URL=http://loki.monitoring.svc.cluster.local:3100 --project=proj_abc123 --org=my-org --env=production --service-id=esvc_abc123
|
|
77
|
-
sylphx config set PUBLIC_URL=https://app.example.com --project=proj_abc123 --org=my-org
|
|
78
|
-
sylphx secrets set --project=proj_abc123 --org=my-org --key STRIPE_SECRET --value sk_live_...
|
|
79
|
-
sylphx storage list --project=proj_abc123 --org=my-org
|
|
80
|
-
sylphx volumes list --project=proj_abc123 --org=my-org
|
|
81
|
-
sylphx resources bind res_abc123 --project=proj_abc123 --org=my-org --env=production
|
|
82
|
-
sylphx run-cmd --project=proj_abc123 --org=my-org --env=production -- bun test
|
|
83
|
-
sylphx promote --project=proj_abc123 --org=my-org --from=staging --to=production --yes
|
|
84
|
-
sylphx releases list --project=proj_abc123 --org=my-org
|
|
29
|
+
export SYLPHX_CLI_BINARY=/path/to/sylphx
|
|
85
30
|
```
|
|
86
31
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
Set `SYLPHX_TOKEN` to a `svc_*` service token for stateless CI, or inject
|
|
90
|
-
`SYLPHX_ACCESS_TOKEN` + `SYLPHX_REFRESH_TOKEN` when a managed credential
|
|
91
|
-
broker owns an OAuth session. Every CLI command honours the active source:
|
|
92
|
-
|
|
93
|
-
- `SYLPHX_ACCESS_TOKEN` + `SYLPHX_REFRESH_TOKEN` wins first. The CLI
|
|
94
|
-
writes the pair into `~/.sylphx/config.json`, then uses the same
|
|
95
|
-
proactive/reactive refresh path and cross-process refresh lock as
|
|
96
|
-
`sylphx login`. `SYLPHX_TOKEN` may supply the access token only when
|
|
97
|
-
`SYLPHX_REFRESH_TOKEN` is present and the token is not `svc_*`.
|
|
98
|
-
- `SYLPHX_TOKEN=svc_...` is next and stays stateless: no login step, no
|
|
99
|
-
browser, no config write.
|
|
100
|
-
- `SYLPHX_TOKEN_FILE` is next in precedence and supports a raw token,
|
|
101
|
-
`SYLPHX_TOKEN=svc_...`, `export SYLPHX_TOKEN="svc_..."`, or
|
|
102
|
-
`SYLPHX_ACCESS_TOKEN=...` + `SYLPHX_REFRESH_TOKEN=...`.
|
|
103
|
-
- If `SYLPHX_TOKEN_FILE` is set but unreadable or empty, the CLI fails
|
|
104
|
-
closed instead of silently using a stored human OAuth session.
|
|
105
|
-
- The OAuth refresh interceptor is skipped only for stateless service
|
|
106
|
-
token sources. Access-token-only OAuth JWTs are short-lived and should
|
|
107
|
-
be paired with `SYLPHX_REFRESH_TOKEN` or replaced by a service token.
|
|
108
|
-
- Empty string (`SYLPHX_TOKEN=`) is treated as unset and falls back to
|
|
109
|
-
the stored session — defends against misconfigured CI shell exports.
|
|
110
|
-
- The same `SYLPHX_TOKEN` GitHub Actions output minted by `sylphx ci
|
|
111
|
-
github-actions` is the variable the CLI itself consumes. One contract,
|
|
112
|
-
no shell glue.
|
|
113
|
-
|
|
114
|
-
GitHub Actions example:
|
|
115
|
-
|
|
116
|
-
```yaml
|
|
117
|
-
- run: sylphx deploy --env=production
|
|
118
|
-
env:
|
|
119
|
-
SYLPHX_TOKEN: ${{ secrets.SYLPHX_TOKEN }}
|
|
120
|
-
```
|
|
32
|
+
## Day-1 shipped commands
|
|
121
33
|
|
|
122
|
-
|
|
34
|
+
| Command | Notes |
|
|
35
|
+
| --- | --- |
|
|
36
|
+
| `sylphx health` | Control-plane health |
|
|
37
|
+
| `sylphx whoami` | Current principal |
|
|
38
|
+
| `sylphx orgs list` | Organizations |
|
|
39
|
+
| `sylphx projects list` | Projects |
|
|
40
|
+
| `sylphx projects get <id>` | Project detail |
|
|
41
|
+
| `sylphx environments list <project_id>` | Environments |
|
|
42
|
+
| `sylphx environments get <project_id> <env_id>` | Environment detail |
|
|
43
|
+
| `sylphx deployments list <project_id>` | Deployments |
|
|
44
|
+
| `sylphx api <METHOD> <path>` | Escape hatch |
|
|
45
|
+
| `sylphx version-info` | Contract identity |
|
|
123
46
|
|
|
124
47
|
```bash
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
sylphx
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
Agents should prefer a scope-limited `svc_*` service token for long-running
|
|
133
|
-
automation. If a broker injects OAuth, inject both access and refresh tokens
|
|
134
|
-
so the CLI can rotate the chain. Do not copy `~/.sylphx/config.json` between
|
|
135
|
-
machines: the OAuth refresh token is single-use rotation state.
|
|
136
|
-
|
|
137
|
-
## Configuration
|
|
138
|
-
|
|
139
|
-
Stored at `~/.sylphx/config.json`:
|
|
140
|
-
|
|
141
|
-
```json
|
|
142
|
-
{
|
|
143
|
-
"oauth": {
|
|
144
|
-
"accessToken": "eyJ...",
|
|
145
|
-
"refreshToken": "ref_...",
|
|
146
|
-
"expiresAt": "2026-04-23T15:00:00.000Z",
|
|
147
|
-
"refreshExpiresAt": "2026-05-23T15:00:00.000Z"
|
|
148
|
-
},
|
|
149
|
-
"defaultOrg": "org_xyz789"
|
|
150
|
-
}
|
|
48
|
+
export SYLPHX_TOKEN=svc_...
|
|
49
|
+
export SYLPHX_API_URL=https://api.sylphx.com/v1 # optional
|
|
50
|
+
sylphx health --json
|
|
51
|
+
sylphx projects list --json
|
|
52
|
+
sylphx environments list prj_demo --json
|
|
151
53
|
```
|
|
152
54
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
```toml
|
|
156
|
-
version = "1"
|
|
157
|
-
|
|
158
|
-
[project]
|
|
159
|
-
id = "proj_abc123"
|
|
160
|
-
name = "My Project"
|
|
161
|
-
slug = "my-project"
|
|
162
|
-
org_id = "org_xyz789"
|
|
163
|
-
org = "my-org"
|
|
164
|
-
default_env = "production"
|
|
165
|
-
default_env_id = "env_prod123"
|
|
166
|
-
```
|
|
167
|
-
|
|
168
|
-
The home config is private operator state only. It does not store per-directory project links.
|
|
169
|
-
|
|
170
|
-
## Environment variables
|
|
171
|
-
|
|
172
|
-
| Variable | Description |
|
|
173
|
-
|---|---|
|
|
174
|
-
| `SYLPHX_TOKEN` | Stateless bearer token for non-interactive auth (CI / agents). Use `svc_*` service tokens. Empty string is treated as unset. |
|
|
175
|
-
| `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. |
|
|
176
|
-
| `SYLPHX_REFRESH_TOKEN` | OAuth refresh token for managed agents. Used only with `SYLPHX_ACCESS_TOKEN` or a non-service-token `SYLPHX_TOKEN`. |
|
|
177
|
-
| `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. |
|
|
178
|
-
| `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. |
|
|
179
|
-
| `SYLPHX_API_URL` | Override API base URL (default: `https://sylphx.com`) |
|
|
180
|
-
|
|
181
|
-
## Commands
|
|
182
|
-
|
|
183
|
-
### Authentication & identity
|
|
184
|
-
|
|
185
|
-
| Command | Purpose |
|
|
186
|
-
|---|---|
|
|
187
|
-
| `sylphx login` | OAuth device flow — browser-based, stores access + refresh tokens |
|
|
188
|
-
| `sylphx logout` | Clear stored credentials |
|
|
189
|
-
| `sylphx whoami` | Show current user + org + linked project |
|
|
190
|
-
|
|
191
|
-
### Diagnostics & raw API
|
|
192
|
-
|
|
193
|
-
| Command | Purpose |
|
|
194
|
-
|---|---|
|
|
195
|
-
| `sylphx doctor` | Diagnose CLI install + auth + linked-project state, including read-only live auth validation |
|
|
196
|
-
| `sylphx api` | Generic authenticated Management API caller (`sylphx api GET /projects`) — like `gh api`; inherits OAuth refresh, idempotency keys, RFC 7807 errors |
|
|
197
|
-
|
|
198
|
-
### Project lifecycle
|
|
199
|
-
|
|
200
|
-
| Command | Purpose |
|
|
201
|
-
|---|---|
|
|
202
|
-
| `sylphx init` | Scaffold a new project |
|
|
203
|
-
| `sylphx link` | Link current directory to a Sylphx app |
|
|
204
|
-
| `sylphx unlink` | Remove the project link |
|
|
205
|
-
| `sylphx open` | Open the linked project, or an explicit project with `--project/--org` |
|
|
206
|
-
| `sylphx projects` | List / manage projects |
|
|
207
|
-
| `sylphx orgs` | Manage organizations (members, invites, roles); `sylphx org` is an alias |
|
|
208
|
-
| `sylphx migrate` | ADR-driven codemods for the linked repo (health-checks wiring, fleet migration status) |
|
|
209
|
-
|
|
210
|
-
### Deployment
|
|
211
|
-
|
|
212
|
-
| Command | Purpose |
|
|
213
|
-
|---|---|
|
|
214
|
-
| `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 |
|
|
215
|
-
| `sylphx deployments` | List / inspect deployments |
|
|
216
|
-
| `sylphx releases` | Browse release history for a linked or explicit project |
|
|
217
|
-
| `sylphx inspect` | Inspect a deployment's build + run metadata |
|
|
218
|
-
| `sylphx bisect` | Git-bisect-style regression hunt across deployments for a linked or explicit project |
|
|
219
|
-
| `sylphx promote` | Promote one environment into another for a linked or explicit project |
|
|
220
|
-
| `sylphx rollback` | Roll back a linked or explicit project deployment |
|
|
221
|
-
| `sylphx status` | Deployment + health status for a linked or explicit project |
|
|
222
|
-
| `sylphx logs` | Inspect bounded runtime logs for a linked or explicit project; add `--follow` for SSE or `--type=build` for deploy logs |
|
|
223
|
-
| `sylphx tail` | Follow runtime logs with structured formatting; accepts the same filters as `logs` |
|
|
224
|
-
| `sylphx run-cmd` | Run a local command with remote env from a linked or explicit project |
|
|
225
|
-
| `sylphx run` | Submit a direct batch run, or a distributed run with `--parallelism`; uses the app server connection URL (`--url` or `SYLPHX_SECRET_URL`) |
|
|
226
|
-
| `sylphx runs` | List, inspect, fetch shard logs for, or cancel submitted direct/distributed runs |
|
|
227
|
-
|
|
228
|
-
`sylphx run-cmd` resolves the target environment through the Management API and
|
|
229
|
-
injects the same customer-authored runtime env vars that a deployed service
|
|
230
|
-
receives. Remote values override same-named local process values so local
|
|
231
|
-
agent/CI smoke tests use production, staging, or preview configuration exactly
|
|
232
|
-
as stored in Platform. Secret values are passed only to the child process; CLI
|
|
233
|
-
status output reports counts, never values.
|
|
234
|
-
|
|
235
|
-
When `sylphx.toml` exists in the working directory, `sylphx deploy` validates
|
|
236
|
-
and publishes that manifest before triggering the deployment. This is the path
|
|
237
|
-
that makes config-as-code fields such as `[database.migrations]` visible to the
|
|
238
|
-
management deploy pipeline. For explicit deploys, pass both project and org
|
|
239
|
-
scope, for example `sylphx deploy --project=proj_abc123 --org=my-org`; the CLI
|
|
240
|
-
uses the same resolved org scope for the manifest publish, deployment trigger,
|
|
241
|
-
log stream, and final deployment-state verification.
|
|
242
|
-
|
|
243
|
-
`--skip-manifest` is an operator recovery escape hatch only. It bypasses local
|
|
244
|
-
manifest publication, so any local `sylphx.toml` changes that have not already
|
|
245
|
-
been persisted, including migration command changes, are not part of that
|
|
246
|
-
deployment.
|
|
247
|
-
|
|
248
|
-
### Direct and distributed runs
|
|
249
|
-
|
|
250
|
-
`sylphx run` submits language-agnostic container batch work to the public BaaS
|
|
251
|
-
Run plane. Pass exactly one image source:
|
|
252
|
-
|
|
253
|
-
- `--image <oci-ref>` for an explicit image from a connected registry.
|
|
254
|
-
- `--image-from-service <name>` to resolve the image from the named service's
|
|
255
|
-
current successful deployment in the same project environment.
|
|
256
|
-
|
|
257
|
-
For distributed work, set `--parallelism N`. The platform injects
|
|
258
|
-
`SYLPHX_SHARD_INDEX` and `SYLPHX_SHARD_COUNT` into every shard. Use
|
|
259
|
-
`--opportunistic` to run on low-priority spare fleet capacity
|
|
260
|
-
(`gangScheduling=false`), and `--backoff-limit-per-index N` to give each shard a
|
|
261
|
-
bounded retry budget after preemption.
|
|
262
|
-
|
|
263
|
-
```bash
|
|
264
|
-
export SYLPHX_SECRET_URL='sylphx://sk_...@pale-tore-0lgrqz.api.sylphx.com'
|
|
265
|
-
|
|
266
|
-
sylphx run \
|
|
267
|
-
--image-from-service trainer \
|
|
268
|
-
--command python --command -m --command trainer.shard \
|
|
269
|
-
--parallelism 8 \
|
|
270
|
-
--opportunistic \
|
|
271
|
-
--backoff-limit-per-index 12 \
|
|
272
|
-
--env TRAINER_UNIVERSE_SIZE=800 \
|
|
273
|
-
--follow
|
|
274
|
-
|
|
275
|
-
sylphx runs list
|
|
276
|
-
sylphx runs get worker_abc123 --parallelism 8
|
|
277
|
-
sylphx runs logs worker_abc123 --parallelism 8 --shard 3
|
|
278
|
-
sylphx runs cancel worker_abc123 --yes
|
|
279
|
-
```
|
|
280
|
-
|
|
281
|
-
### Preview capacity and service build context
|
|
282
|
-
|
|
283
|
-
Project preview capacity is a public project-level override. It controls how
|
|
284
|
-
many PR preview environments may be active for that project before platform
|
|
285
|
-
backpressure leaves new preview webhooks queued under `sylphx/preview`. Leave
|
|
286
|
-
the value unset to follow the organization plan.
|
|
287
|
-
|
|
288
|
-
```bash
|
|
289
|
-
sylphx projects preview-capacity get proj_abc123 --output json
|
|
290
|
-
sylphx projects preview-capacity set proj_abc123 10
|
|
291
|
-
sylphx projects preview-capacity clear proj_abc123
|
|
292
|
-
```
|
|
293
|
-
|
|
294
|
-
Service build source layout remains service-scoped. Use
|
|
295
|
-
`sylphx services update` when a service needs a Dockerfile path, build context,
|
|
296
|
-
or command override without changing the project-level manifest contract.
|
|
297
|
-
|
|
298
|
-
```bash
|
|
299
|
-
sylphx services update web \
|
|
300
|
-
--project=proj_abc123 \
|
|
301
|
-
--org=my-org \
|
|
302
|
-
--dockerfile=apps/web/Dockerfile \
|
|
303
|
-
--build-context=. \
|
|
304
|
-
--build-command="bun run build"
|
|
305
|
-
```
|
|
306
|
-
|
|
307
|
-
### Managed primitives
|
|
308
|
-
|
|
309
|
-
| Command | Purpose |
|
|
310
|
-
|---|---|
|
|
311
|
-
| `sylphx db` | Manage PostgreSQL databases (CNPG-backed) |
|
|
312
|
-
| `sylphx preview` | Preview environment management (branch DB, keep-alive, …) |
|
|
313
|
-
| `sylphx previews` | Per-PR preview cost browser (ADR-137) |
|
|
314
|
-
| `sylphx storage` | Manage object storage buckets for a linked or explicit project (Ceph S3) |
|
|
315
|
-
| `sylphx volumes` | Manage persistent volumes for a linked or explicit project (Rook-Ceph RWO/RWX) |
|
|
316
|
-
| `sylphx workspaces` | Manage Platform workspace handles for a linked or explicit project |
|
|
317
|
-
| `sylphx agent-resources` | Inspect the project Agent Resource Graph across Platform-owned resources |
|
|
318
|
-
| `sylphx mobile-device-tests` | Create, list, poll, and cancel managed Android/iOS device-runtime test requests |
|
|
319
|
-
| `sylphx device-sessions` | Drive an interactive Android device session — boot, install, tap/swipe/key/text, screenshot, launch, logcat, terminate |
|
|
320
|
-
| `sylphx resources` | Bind / unbind shared resources for a linked or explicit project |
|
|
321
|
-
| `sylphx services` | List + deploy service blueprints |
|
|
322
|
-
| `sylphx config` | Per-environment app config for a linked or explicit project |
|
|
323
|
-
| `sylphx env` | Environment variables and environments for a linked or explicit project |
|
|
324
|
-
| `sylphx secrets` | Encrypted project secrets for a linked or explicit project |
|
|
325
|
-
| `sylphx tasks` | Task definitions (job / cron / service) for a linked or explicit project |
|
|
326
|
-
| `sylphx domains` | Custom domains + TLS for a linked or explicit project |
|
|
327
|
-
| `sylphx sandbox` | Interactive sandbox environments for a linked or explicit project |
|
|
328
|
-
| `sylphx runners` | Self-hosted runner admin |
|
|
329
|
-
|
|
330
|
-
Mobile device tests run on the managed device-runtime plane, not inside the
|
|
331
|
-
default sandbox workspace. Build APK/AAB/IPA artifacts in CI, store them behind
|
|
332
|
-
artifact handles, then submit the handles and device matrix:
|
|
333
|
-
|
|
334
|
-
```bash
|
|
335
|
-
sylphx mobile-device-tests create \
|
|
336
|
-
--project=proj_abc123 \
|
|
337
|
-
--framework=maestro \
|
|
338
|
-
--app-kind=apk \
|
|
339
|
-
--app-uri=resource://artifacts/app-debug.apk \
|
|
340
|
-
--test-kind=zip \
|
|
341
|
-
--test-uri=resource://artifacts/mobile-tests.zip \
|
|
342
|
-
--device=android:emulator:35:Pixel-8
|
|
343
|
-
|
|
344
|
-
sylphx mobile-device-tests list --project=proj_abc123 --status=waiting-for-capacity
|
|
345
|
-
sylphx mobile-device-tests get mdt_abc123
|
|
346
|
-
sylphx mobile-device-tests cancel mdt_abc123
|
|
347
|
-
```
|
|
348
|
-
|
|
349
|
-
A **device session** is the interactive counterpart: a long-lived Android device
|
|
350
|
-
you drive in real time — boot once, then install, screenshot, and send input
|
|
351
|
-
until you tear it down. The agent perceives the device through `screenshot` and
|
|
352
|
-
acts through `input`, exactly like computer-use. See
|
|
353
|
-
[docs/how-to/drive-android-device-session.md](../../docs/how-to/drive-android-device-session.md)
|
|
354
|
-
for the full loop with CLI and curl examples.
|
|
355
|
-
|
|
356
|
-
```bash
|
|
357
|
-
# Boot a device and block until it is ready (prints the dvs_ id).
|
|
358
|
-
sylphx device-sessions create --project=proj_abc123 --wait
|
|
359
|
-
|
|
360
|
-
# Install, launch, see the screen, then act on it.
|
|
361
|
-
sylphx device-sessions install dvs_abc123 https://example.com/app-debug.apk
|
|
362
|
-
sylphx device-sessions launch dvs_abc123
|
|
363
|
-
sylphx device-sessions screenshot dvs_abc123 -o screen.png --open
|
|
364
|
-
sylphx device-sessions input dvs_abc123 tap 540 1200
|
|
365
|
-
sylphx device-sessions input dvs_abc123 text "hello world"
|
|
366
|
-
|
|
367
|
-
sylphx device-sessions list --project=proj_abc123
|
|
368
|
-
sylphx device-sessions rm dvs_abc123 --yes
|
|
369
|
-
```
|
|
370
|
-
|
|
371
|
-
### Integration primitives
|
|
372
|
-
|
|
373
|
-
| Command | Purpose |
|
|
374
|
-
|---|---|
|
|
375
|
-
| `sylphx backup` | Managed data backup + restore |
|
|
376
|
-
| `sylphx webhooks` | Outbound webhook endpoint CRUD |
|
|
377
|
-
| `sylphx flags` | Feature flag admin |
|
|
378
|
-
| `sylphx realtime` | Realtime channel admin |
|
|
379
|
-
| `sylphx saml` | SAML SSO configuration |
|
|
380
|
-
| `sylphx ai` | AI model / completion admin |
|
|
381
|
-
| `sylphx session-replay` | Session replay admin |
|
|
382
|
-
| `sylphx search` | Search index admin |
|
|
383
|
-
| `sylphx engagement` | Engagement campaign admin |
|
|
384
|
-
| `sylphx consent` | GDPR / CCPA consent admin |
|
|
385
|
-
| `sylphx privacy` | Privacy / data-subject-request admin |
|
|
386
|
-
| `sylphx referrals` | Referral program admin |
|
|
387
|
-
| `sylphx newsletter` | Newsletter admin |
|
|
388
|
-
|
|
389
|
-
### Billing & scale
|
|
390
|
-
|
|
391
|
-
| Command | Purpose |
|
|
392
|
-
|---|---|
|
|
393
|
-
| `sylphx plan` | View / upgrade plan for a linked or explicit project |
|
|
394
|
-
| `sylphx billing` | Invoices, payment methods |
|
|
395
|
-
| `sylphx experiments` | A/B experiment admin |
|
|
396
|
-
| `sylphx analytics` | Analytics admin queries |
|
|
397
|
-
|
|
398
|
-
### Observability & integrations
|
|
399
|
-
|
|
400
|
-
| Command | Purpose |
|
|
401
|
-
|---|---|
|
|
402
|
-
| `sylphx monitoring` | Metric + alert admin |
|
|
403
|
-
| `sylphx insights` | Customer-facing latency dashboards — rolling 7-day merge-to-live rollups (ADR-136) |
|
|
404
|
-
| `sylphx health` | Audit + verification subcommands for service health, e.g. `health verify --file` for exported audit hash chains (ADR-144) |
|
|
405
|
-
| `sylphx certs` | TLS certificate inspection |
|
|
406
|
-
| `sylphx email` | Transactional email admin |
|
|
407
|
-
| `sylphx notifications` | Push / in-app notification admin |
|
|
408
|
-
|
|
409
|
-
### Machine identity & policy
|
|
410
|
-
|
|
411
|
-
| Command | Purpose |
|
|
412
|
-
|---|---|
|
|
413
|
-
| `sylphx tokens` | Service token issuance + revocation |
|
|
414
|
-
| `sylphx oidc` | OIDC federation (GitHub Actions, GitLab CI, …) |
|
|
415
|
-
| `sylphx ci` | CI integration helpers (generates workflow snippets) |
|
|
416
|
-
|
|
417
|
-
### Account & administration
|
|
418
|
-
|
|
419
|
-
| Command | Purpose |
|
|
420
|
-
|---|---|
|
|
421
|
-
| `sylphx account` | Account-level operations (verified email change, …) |
|
|
422
|
-
| `sylphx user` | Current-user self-service: profile, sessions, security posture, data export |
|
|
423
|
-
| `sylphx users` | Platform-admin user directory (list / get / role / verify-email / delete / revoke-sessions) |
|
|
424
|
-
| `sylphx admin` | Platform-admin operations (quotas, tenants, builds, reconcile, …) — requires platform-operator scopes |
|
|
425
|
-
| `sylphx rate-limits` | Inspect + tune BaaS rate-limit strategy overrides (ADR-089) |
|
|
426
|
-
|
|
427
|
-
## Architecture
|
|
428
|
-
|
|
429
|
-
- 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.
|
|
430
|
-
- `BunRuntime.runMain` is the single `runPromise`-like call site (ADR-058 Rule 21).
|
|
431
|
-
- Management plane only (ADR-083) — runtime BaaS verbs (`kv.*`, `email.send`, `flags.evaluate`, …) live inside the deployed application via [`@sylphx/sdk`](https://www.npmjs.com/package/@sylphx/sdk).
|
|
432
|
-
- Types derive from [`@sylphx/contract`](https://www.npmjs.com/package/@sylphx/contract) (Effect Schema SSOT, ADR-084). Hand-written wire types are a bug.
|
|
433
|
-
- HTTP client is `@sylphx/management` bundled in via `tsup noExternal` — global install has zero workspace peers to resolve.
|
|
434
|
-
|
|
435
|
-
## Version compatibility
|
|
436
|
-
|
|
437
|
-
| CLI | Management API | Contract |
|
|
438
|
-
|---|---|---|
|
|
439
|
-
| `@sylphx/cli@0.x` (beta) | `api.sylphx.com/v1` | `@sylphx/contract` (workspace / beta) |
|
|
440
|
-
|
|
441
|
-
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.
|
|
442
|
-
|
|
443
|
-
## Development
|
|
444
|
-
|
|
445
|
-
```bash
|
|
446
|
-
bun install
|
|
447
|
-
bun run dev -- --help # Run CLI against workspace
|
|
448
|
-
bun run build # Build production bundle via tsup
|
|
449
|
-
bun test # Run test suite (bun test)
|
|
450
|
-
```
|
|
451
|
-
|
|
452
|
-
Shared table-formatting helpers under `packages/cli/src/utils/` are internal
|
|
453
|
-
presentation utilities. Moving identical helpers out of command modules must
|
|
454
|
-
preserve command names, flags, JSON fields, and human-readable output strings;
|
|
455
|
-
otherwise update this README, the public docs, and command tests in the same
|
|
456
|
-
change.
|
|
457
|
-
|
|
458
|
-
## Related packages
|
|
459
|
-
|
|
460
|
-
- [`@sylphx/management`](https://www.npmjs.com/package/@sylphx/management) — Promise SDK the CLI is built on (bundled).
|
|
461
|
-
- [`@sylphx/contract`](https://www.npmjs.com/package/@sylphx/contract) — Effect Schema SSOT (bundled).
|
|
462
|
-
- [`@sylphx/sdk`](https://www.npmjs.com/package/@sylphx/sdk) — runtime BaaS SDK for deployed apps.
|
|
55
|
+
## Versioning
|
|
463
56
|
|
|
464
|
-
|
|
57
|
+
- **npm package** `@sylphx/cli` version (this package) follows the npm channel.
|
|
58
|
+
- **Binary** `--version` reports the Rust crate `sylphx-cli` version (see
|
|
59
|
+
`package.json#sylphx.crateVersion`).
|
|
465
60
|
|
|
466
|
-
|
|
61
|
+
Wire SSOT: Protobuf under `api/proto` (`sylphx.platform.v1`). App library:
|
|
62
|
+
`@sylphx/sdk` (TypeScript) / `sylphx-sdk` (Rust).
|
package/bin/run.js
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
'use strict'
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Thin npm bin shim for the Rust `sylphx` binary.
|
|
6
|
+
* Does not reimplement CLI logic — only resolves and execs the native binary.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
const { spawn } = require('node:child_process')
|
|
10
|
+
const { getBinaryPath } = require('../lib/get-binary')
|
|
11
|
+
|
|
12
|
+
function main() {
|
|
13
|
+
let binary
|
|
14
|
+
try {
|
|
15
|
+
binary = getBinaryPath()
|
|
16
|
+
} catch (err) {
|
|
17
|
+
console.error(err && err.message ? err.message : String(err))
|
|
18
|
+
process.exit(1)
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
const args = process.argv.slice(2)
|
|
22
|
+
const child = spawn(binary, args, {
|
|
23
|
+
stdio: 'inherit',
|
|
24
|
+
windowsHide: true,
|
|
25
|
+
})
|
|
26
|
+
|
|
27
|
+
child.on('error', (err) => {
|
|
28
|
+
console.error(`Failed to execute ${binary}: ${err.message}`)
|
|
29
|
+
process.exit(1)
|
|
30
|
+
})
|
|
31
|
+
|
|
32
|
+
child.on('exit', (code, signal) => {
|
|
33
|
+
if (signal) {
|
|
34
|
+
process.kill(process.pid, signal)
|
|
35
|
+
return
|
|
36
|
+
}
|
|
37
|
+
process.exit(code == null ? 1 : code)
|
|
38
|
+
})
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
main()
|
|
Binary file
|
package/install.js
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* postinstall: soft-check that the platform optionalDependency landed.
|
|
5
|
+
* Never hard-fails install on optional-missing (npm already soft-fails optionals);
|
|
6
|
+
* prints a clear warning so operators see cargo fallback immediately.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
const { platformPackageName, platformKey } = require('./lib/platform')
|
|
10
|
+
const { getBinaryPath } = require('./lib/get-binary')
|
|
11
|
+
|
|
12
|
+
function main() {
|
|
13
|
+
// Skip in CI pack / offline contexts that set this intentionally
|
|
14
|
+
if (process.env.SYLPHX_CLI_SKIP_POSTINSTALL === '1') {
|
|
15
|
+
return
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
try {
|
|
19
|
+
const bin = getBinaryPath()
|
|
20
|
+
if (process.env.SYLPHX_CLI_INSTALL_VERBOSE === '1') {
|
|
21
|
+
console.log(`@sylphx/cli: native binary ready at ${bin}`)
|
|
22
|
+
}
|
|
23
|
+
} catch {
|
|
24
|
+
const pkg = platformPackageName() || '(unsupported platform)'
|
|
25
|
+
console.warn(
|
|
26
|
+
[
|
|
27
|
+
'',
|
|
28
|
+
`[@sylphx/cli] Native binary for ${platformKey()} not found after install.`,
|
|
29
|
+
` Expected optional package: ${pkg}`,
|
|
30
|
+
' Fallbacks: cargo install sylphx-cli | export SYLPHX_CLI_BINARY=/path/to/sylphx',
|
|
31
|
+
'',
|
|
32
|
+
].join('\n'),
|
|
33
|
+
)
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
main()
|