@statechange/xano-cli 0.3.0 → 0.3.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/README.md CHANGED
@@ -53,28 +53,20 @@ sc-xano audit workspace
53
53
 
54
54
  Once authenticated, the CLI auto-resolves your Xano instance, workspace, and token from the StateChange backend. No extra flags needed if you have a single instance.
55
55
 
56
- ## Authentication & Session Management
56
+ ## Commands
57
57
 
58
- The CLI uses a StateChange API key to fetch Xano credentials automatically:
58
+ ### `auth` Authentication & Session Management
59
59
 
60
60
  ```bash
61
- # Interactive setup
62
- sc-xano auth init
63
-
64
- # Or provide key directly
65
- sc-xano auth init --api-key <key>
66
-
67
- # Check auth status
68
- sc-xano auth whoami
69
-
70
- # Check Xano token health
71
- sc-xano auth status
72
-
73
- # Override defaults
74
- sc-xano auth set-instance <hostname> --workspace <id>
61
+ sc-xano auth init # Interactive API key setup
62
+ sc-xano auth init --api-key <key> # Direct API key setup
63
+ sc-xano auth whoami # Verify auth and list instances
64
+ sc-xano auth status # Check Xano token health and session freshness
65
+ sc-xano auth set-instance <host> # Save default instance
66
+ sc-xano auth set-instance <host> --workspace <id> # Save default instance and workspace
75
67
  ```
76
68
 
77
- ### Session Freshness
69
+ #### Session Freshness
78
70
 
79
71
  Your Xano session token is refreshed whenever you open Xano in the browser with the StateChange extension active. The CLI monitors token health automatically:
80
72
 
@@ -83,158 +75,190 @@ Your Xano session token is refreshed whenever you open Xano in the browser with
83
75
  - **Expired token** — a warning is shown; if Xano rejects the request, the CLI prompts you to open Xano and polls until the session is refreshed
84
76
  - **401/403 errors** — the CLI advises running `auth status` to diagnose
85
77
 
86
- Run `sc-xano auth status` at any time to check your session.
87
-
88
- ### Fallback Options
89
-
90
- You can also provide credentials directly via flags or environment variables:
91
-
92
- | Flag | Environment Variable | Description |
93
- |------|---------------------|-------------|
94
- | `--api-key` | `STATECHANGE_API_KEY` | StateChange API key |
95
- | `--instance` | `XANO_INSTANCE` | Xano instance hostname |
96
- | `--workspace` | `XANO_WORKSPACE` | Workspace ID |
97
- | `--token` | `XANO_TOKEN` | Xano API token |
98
- | `--branch` | — | Branch ID (default: 0) |
99
- | `--format` | — | Output format: `table`, `json`, or `yaml` |
100
-
101
- All commands support `--format table` (default, human-readable), `--format json`, and `--format yaml`. The yaml format is recommended for AI/LLM consumption.
102
-
103
- ## Commands
104
-
105
78
  ### `performance` — Performance Analysis
106
79
 
107
80
  Find slow endpoints, trace execution bottlenecks, and deep-dive into request stacks.
108
81
 
109
82
  ```bash
110
- # Top slowest endpoints (last 24 hours)
111
- sc-xano performance top-endpoints
112
- sc-xano performance top-endpoints --lookback 48 --limit 10
83
+ # Rank all endpoints/tasks/triggers by total server time
84
+ sc-xano performance top-endpoints # Last 24 hours
85
+ sc-xano performance top-endpoints --lookback 48 # Custom lookback (hours)
86
+ sc-xano performance top-endpoints --limit 10 # Limit results
113
87
 
114
88
  # Trace: aggregate stack analysis across multiple executions
115
- sc-xano performance trace endpoint <query-id> --samples 10
116
- sc-xano performance trace task <task-id> --samples 10
117
- sc-xano performance trace trigger <trigger-id> --samples 10
89
+ sc-xano performance trace endpoint <query-id> # Endpoint trace
90
+ sc-xano performance trace task <task-id> # Task trace
91
+ sc-xano performance trace trigger <trigger-id> # Trigger trace
92
+ sc-xano performance trace endpoint <id> --samples 20 # Custom sample count
118
93
 
119
94
  # Deep-dive: full stack expansion for a single request
120
95
  sc-xano performance deep-dive <request-id>
121
96
 
122
- # Scan functions for nested slow steps
97
+ # Scan all functions for nested slow steps
123
98
  sc-xano performance scan-functions
124
- sc-xano performance scan-functions --min-nesting 3
125
-
126
- # Use yaml for AI-driven analysis
127
- sc-xano performance top-endpoints --format yaml
128
- sc-xano performance deep-dive <request-id> --format yaml
99
+ sc-xano performance scan-functions --min-nesting 3 # Custom nesting threshold
129
100
  ```
130
101
 
131
- **Trace** aggregates timing data across N samples, showing duration percentiles (avg, p50, p95, p99) and per-step breakdown by `_xsid`.
102
+ **Trace** aggregates timing data across N samples, showing duration percentiles (avg, p50, p95, p99) and per-step breakdown by `_xsid`. Steps with high occurrences relative to samples indicate they run inside loops.
132
103
 
133
- **Deep-dive** expands a single request's stack into a tree with direct vs rollup timing, percentage breakdowns, loop iteration counts, and warnings for slow steps inside loops (N+1 queries, lambda blocks, external API calls).
104
+ **Deep-dive** expands a single request's stack into a recursive tree with direct vs rollup timing, percentage breakdowns (`pct_of_total`, `pct_of_parent`), loop iteration counts, and warnings for slow steps inside loops (N+1 queries, lambda blocks, external API calls).
134
105
 
135
106
  ### `xray` — Function Analysis
136
107
 
137
- Analyze function internals: step hierarchy, performance warnings, dependencies.
108
+ Static analysis of function internals: step hierarchy, performance warnings, dependencies on other functions.
138
109
 
139
110
  ```bash
140
- sc-xano xray function --id <function-id>
141
- sc-xano xray scan-workspace
142
- sc-xano xray scan-workspace --include-warnings
111
+ sc-xano xray function --id <function-id> # Analyze a single function
112
+ sc-xano xray scan-workspace # Scan all functions for errors
113
+ sc-xano xray scan-workspace --include-warnings # Include warnings (not just errors)
143
114
  ```
144
115
 
145
116
  ### `audit` — Security Auditing
146
117
 
118
+ Audit workspace objects for configuration issues, unsecured endpoints, and schema problems.
119
+
147
120
  ```bash
148
- sc-xano audit workspace # API configurations
149
- sc-xano audit swagger # Unsecured Swagger endpoints
150
- sc-xano audit database # Table schemas and indexes
151
- sc-xano audit middleware
152
- sc-xano audit addons
153
- sc-xano audit tasks
154
- sc-xano audit triggers
155
- sc-xano audit mcp-servers
121
+ sc-xano audit workspace # Audit all API group configurations
122
+ sc-xano audit swagger # Find unsecured Swagger/documentation endpoints
123
+ sc-xano audit database # Audit table schemas, indexes, and relationships
124
+ sc-xano audit middleware # Audit middleware configurations
125
+ sc-xano audit addons # Audit addon configurations
126
+ sc-xano audit tasks # Audit background task configurations
127
+ sc-xano audit triggers # Audit trigger configurations
128
+ sc-xano audit mcp-servers # Audit MCP/toolset server configurations
156
129
  ```
157
130
 
158
131
  ### `secure` — Security Management
159
132
 
133
+ Apply security changes to workspace objects.
134
+
160
135
  ```bash
161
- sc-xano secure swagger --app-id <id> --disable # Disable Swagger
162
- sc-xano secure swagger --app-id <id> --require-token # Require token
136
+ sc-xano secure swagger --app-id <id> --disable # Disable Swagger entirely
137
+ sc-xano secure swagger --app-id <id> --require-token # Require token for Swagger access
163
138
  ```
164
139
 
165
140
  ### `history` — Execution History
166
141
 
142
+ Browse request, task, trigger, and MCP server execution history.
143
+
167
144
  ```bash
168
- sc-xano history requests # Recent API requests
145
+ # API request history
146
+ sc-xano history requests # Recent requests (page 1)
169
147
  sc-xano history requests --page 2 # Paginate
170
- sc-xano history request <request-id> # Detailed request info
171
- sc-xano history tasks <task-id> # Task execution history
148
+ sc-xano history request <request-id> # Full request detail (stack, timing, I/O)
149
+
150
+ # Task history
151
+ sc-xano history tasks <task-id> # List task executions
172
152
  sc-xano history task-run <task-id> <run-id> # Detailed task run
173
- sc-xano history triggers <trigger-id> # Trigger history
174
- sc-xano history mcp-servers <tool-id> # MCP server history
153
+
154
+ # Trigger history
155
+ sc-xano history triggers <trigger-id> # List trigger executions
156
+
157
+ # MCP server history
158
+ sc-xano history mcp-servers <tool-id> # List MCP server executions
175
159
  ```
176
160
 
177
161
  ### `logs` — Log Retention Management
178
162
 
179
- View and control how much execution history Xano retains per endpoint, task, or trigger.
163
+ View and control how much execution history Xano retains per endpoint, task, or trigger. Useful when performance deep-dives show `stack_truncated: true`.
180
164
 
181
165
  ```bash
182
166
  # View retention settings
183
- sc-xano logs show # All objects
184
- sc-xano logs show --custom-only # Only non-default settings
167
+ sc-xano logs show # All objects' retention settings
168
+ sc-xano logs show --custom-only # Only objects with non-default settings
185
169
  sc-xano logs show endpoint <id> # Single endpoint with parent app context
186
- sc-xano logs show app <id> # App + all its endpoints
170
+ sc-xano logs show app <id> # App and all its child endpoints
171
+ sc-xano logs show task <id> # Single task
172
+ sc-xano logs show trigger <id> # Single trigger
187
173
 
188
174
  # Update retention
189
- sc-xano logs set endpoint <id> --limit -1 # Unlimited (for debugging)
190
- sc-xano logs set endpoint <id> --limit 100 # Default
191
- sc-xano logs set endpoint <id> --limit 0 # Disable
175
+ sc-xano logs set endpoint <id> --limit -1 # Unlimited (capture full stacks for debugging)
176
+ sc-xano logs set endpoint <id> --limit 100 # Default (top 100 stack steps)
177
+ sc-xano logs set endpoint <id> --limit 0 # Disable history retention
178
+ sc-xano logs set task <id> --limit -1 # Works for tasks too
179
+ sc-xano logs set trigger <id> --limit -1 # And triggers
192
180
 
193
181
  # Watch for new executions in real-time
194
- sc-xano logs watch endpoint <id>
182
+ sc-xano logs watch endpoint <id> # Poll and display new executions as they arrive
195
183
  ```
196
184
 
197
- Useful when performance deep-dives show `stack_truncated: true` — set the limit to unlimited, trigger a new execution, then deep-dive the untruncated result.
198
-
199
185
  ### `inventory` — Workspace Overview
200
186
 
187
+ List and count all objects in your workspace.
188
+
201
189
  ```bash
202
190
  sc-xano inventory workspace # Object counts summary
203
- sc-xano inventory functions # List functions with tags
204
- sc-xano inventory tables # List database tables
205
- sc-xano inventory tasks # List background tasks
206
- sc-xano inventory triggers # List triggers
207
- sc-xano inventory addons # List addons
208
- sc-xano inventory middleware # List middleware
209
- sc-xano inventory mcp-servers # List MCP/toolset servers
191
+ sc-xano inventory functions # List all functions with tags
192
+ sc-xano inventory tables # List all database tables
193
+ sc-xano inventory tasks # List all background tasks
194
+ sc-xano inventory triggers # List all triggers
195
+ sc-xano inventory addons # List all addons
196
+ sc-xano inventory middleware # List all middleware
197
+ sc-xano inventory mcp-servers # List all MCP/toolset servers
210
198
  ```
211
199
 
212
200
  ### `xanoscript` — XanoScript Generation
213
201
 
202
+ Generate XanoScript source code from live Xano objects. Supports all object types.
203
+
214
204
  ```bash
205
+ # Generate XanoScript for a single object
215
206
  sc-xano xanoscript generate function <id>
216
207
  sc-xano xanoscript generate table <id>
217
208
  sc-xano xanoscript generate api <id>
209
+ sc-xano xanoscript generate task <id>
210
+ sc-xano xanoscript generate trigger <id>
211
+ sc-xano xanoscript generate mcp_server <id>
212
+ sc-xano xanoscript generate addon <id>
213
+ sc-xano xanoscript generate middleware <id>
218
214
 
215
+ # Bulk export all objects of a type to .xs files
219
216
  sc-xano xanoscript export-all --type function
220
- sc-xano xanoscript export-all --type table --output-dir ./backup
217
+ sc-xano xanoscript export-all --type table
218
+ sc-xano xanoscript export-all --type api
219
+ sc-xano xanoscript export-all --type task
220
+ sc-xano xanoscript export-all --type trigger
221
+ sc-xano xanoscript export-all --type mcp_server
222
+ sc-xano xanoscript export-all --type addon
223
+ sc-xano xanoscript export-all --type middleware
224
+ sc-xano xanoscript export-all --type function --output-dir ./backup # Custom output directory
221
225
  ```
222
226
 
223
227
  ### `health` — Instance Health & Restarts
224
228
 
229
+ Instance-level operations for monitoring and recovery.
230
+
225
231
  ```bash
226
- sc-xano health instances
227
- sc-xano health database --instance-id <id>
228
- sc-xano health clear-history --instance-id <id>
229
- sc-xano health restart-tasks --instance-id <id>
232
+ sc-xano health instances # List all instances with status
233
+ sc-xano health database --instance-id <id> # Show history database sizes
234
+ sc-xano health clear-history --instance-id <id> # Clear history databases
235
+ sc-xano health clear-history --instance-id <id> --tables request_history,task_history # Clear specific tables
236
+ sc-xano health restart-tasks --instance-id <id> # Restart the task service deployment
230
237
  ```
231
238
 
232
239
  ### `flush` — Cache Management
233
240
 
241
+ The CLI caches workspace data in-memory for 60 seconds. Use `flush` when you know data has changed externally.
242
+
234
243
  ```bash
235
- sc-xano flush # Clear cached sink data
244
+ sc-xano flush
236
245
  ```
237
246
 
247
+ ## Common Flags
248
+
249
+ These flags work on most commands but are usually auto-resolved:
250
+
251
+ | Flag | Environment Variable | Description |
252
+ |------|---------------------|-------------|
253
+ | `--api-key <key>` | `STATECHANGE_API_KEY` | StateChange API key |
254
+ | `--instance <host>` | `XANO_INSTANCE` | Xano instance hostname |
255
+ | `--workspace <id>` | `XANO_WORKSPACE` | Workspace ID |
256
+ | `--token <token>` | `XANO_TOKEN` | Xano API token |
257
+ | `--branch <id>` | — | Branch ID (default: 0) |
258
+ | `--format <fmt>` | — | Output format: `table` (default), `json`, or `yaml` |
259
+
260
+ Use `--format yaml` when feeding output to an AI/LLM — it is the most token-efficient structured format.
261
+
238
262
  ## License
239
263
 
240
264
  MIT
package/dist/index.js CHANGED
@@ -18,8 +18,8 @@ import { flushSinkCache } from "./xano-client.js";
18
18
  const program = new Command();
19
19
  program
20
20
  .name("sc-xano")
21
- .description("StateChange CLI for Xano - workspace management, performance analysis, and operational insights")
22
- .version("0.3.0");
21
+ .description("StateChange CLI for Xano - performance analysis, operational insights, and critical security and restart abilities")
22
+ .version("0.3.1");
23
23
  // Add subcommands
24
24
  createAuthCommand(program);
25
25
  createXRayCommand(program);
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,SAAS,CAAC;KACf,WAAW,CAAC,iGAAiG,CAAC;KAC9G,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,kBAAkB;AAClB,iBAAiB,CAAC,OAAO,CAAC,CAAC;AAC3B,iBAAiB,CAAC,OAAO,CAAC,CAAC;AAC3B,wBAAwB,CAAC,OAAO,CAAC,CAAC;AAClC,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAC5B,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,sBAAsB,CAAC,OAAO,CAAC,CAAC;AAChC,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,uBAAuB,CAAC,OAAO,CAAC,CAAC;AACjC,iBAAiB,CAAC,OAAO,CAAC,CAAC;AAE3B,kCAAkC;AAClC,OAAO;KACJ,OAAO,CAAC,OAAO,CAAC;KAChB,WAAW,CAAC,iDAAiD,CAAC;KAC9D,MAAM,CAAC,GAAG,EAAE;IACX,cAAc,EAAE,CAAC;IACjB,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AAChC,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,SAAS,CAAC;KACf,WAAW,CAAC,oHAAoH,CAAC;KACjI,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,kBAAkB;AAClB,iBAAiB,CAAC,OAAO,CAAC,CAAC;AAC3B,iBAAiB,CAAC,OAAO,CAAC,CAAC;AAC3B,wBAAwB,CAAC,OAAO,CAAC,CAAC;AAClC,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAC5B,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,sBAAsB,CAAC,OAAO,CAAC,CAAC;AAChC,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,uBAAuB,CAAC,OAAO,CAAC,CAAC;AACjC,iBAAiB,CAAC,OAAO,CAAC,CAAC;AAE3B,kCAAkC;AAClC,OAAO;KACJ,OAAO,CAAC,OAAO,CAAC;KAChB,WAAW,CAAC,iDAAiD,CAAC;KAC9D,MAAM,CAAC,GAAG,EAAE;IACX,cAAc,EAAE,CAAC;IACjB,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AAChC,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@statechange/xano-cli",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "CLI for Xano performance analysis, operational insights, and critical security and restart abilities",
5
5
  "type": "module",
6
6
  "bin": {
@@ -97,13 +97,23 @@ npx @statechange/xano-cli logs set endpoint <id> --limit 100 # Set to def
97
97
  npx @statechange/xano-cli logs watch endpoint <id> # Poll for new executions
98
98
  ```
99
99
 
100
- ### XanoScript
100
+ ### XanoScript Generation
101
101
 
102
102
  ```bash
103
+ # Generate for any object type
103
104
  npx @statechange/xano-cli xanoscript generate function <id>
104
105
  npx @statechange/xano-cli xanoscript generate table <id>
105
106
  npx @statechange/xano-cli xanoscript generate api <id>
107
+ npx @statechange/xano-cli xanoscript generate task <id>
108
+ npx @statechange/xano-cli xanoscript generate trigger <id>
109
+ npx @statechange/xano-cli xanoscript generate mcp_server <id>
110
+ npx @statechange/xano-cli xanoscript generate addon <id>
111
+ npx @statechange/xano-cli xanoscript generate middleware <id>
112
+
113
+ # Bulk export all objects of a type
106
114
  npx @statechange/xano-cli xanoscript export-all --type function
115
+ npx @statechange/xano-cli xanoscript export-all --type table
116
+ npx @statechange/xano-cli xanoscript export-all --type function --output-dir ./backup
107
117
  ```
108
118
 
109
119
  ### Instance Health (Master API)