simceptor-cli 1.0.0 β 1.0.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 +82 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# simceptor-cli
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/simceptor-cli)
|
|
4
|
+
[](https://github.com/ayda212/simualtorv2)
|
|
5
|
+
[](https://simceptor.com)
|
|
6
|
+
|
|
7
|
+
> Securely route and test webhook events from the cloud directly to your local development serverβno public tunnels (like Ngrok) or firewall modifications required.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## π€ What is Simceptor?
|
|
12
|
+
|
|
13
|
+
**[Simceptor](https://github.com/ayda212/simualtorv2)** is an advanced, AI-native Mock API & Simulator Platform. It enables developers and QA engineers to:
|
|
14
|
+
|
|
15
|
+
- π― **Define Conditional Logic** (IF-THEN response rules based on body, headers, query params, or path).
|
|
16
|
+
- β±οΈ **Simulate Latency** (per-endpoint or per-rule network delay simulation).
|
|
17
|
+
- π **Inject Dynamic Data** (using template engines and Faker variables).
|
|
18
|
+
- π€ **Work alongside AI Agents** (built-in Model Context Protocol / MCP Server).
|
|
19
|
+
- π **Relay Webhooks locally** using this CLI tool.
|
|
20
|
+
|
|
21
|
+
*Curious about Simceptor? Check out the main repository and build complex API scenarios without writing a single line of backend mock server code.*
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## β‘ The Webhook Localhost Problem
|
|
26
|
+
|
|
27
|
+
Testing webhook callback architectures locally is notoriously painful. Hosted cloud providers (like Stripe, Twilio, or payment gateways) cannot send callback HTTP requests directly to `http://localhost:3000` because your local machine is behind a router, firewall, or NAT.
|
|
28
|
+
|
|
29
|
+
**`simceptor-cli` bridges this gap.**
|
|
30
|
+
|
|
31
|
+
Instead of exposing your local server to the public internet using tools like Ngrok or configuring complex reverse-proxies:
|
|
32
|
+
1. Configure your webhook targets in Simceptor using the `simceptor://local/` URL scheme (e.g. `simceptor://local/api/payment/success`).
|
|
33
|
+
2. Run this lightweight CLI client on your local computer.
|
|
34
|
+
3. The CLI opens a persistent WebSocket connection to your Simceptor server, securely relays incoming webhooks, forwards them to your local running app, and reports the responses back to Simceptor's dashboard logs.
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## π Installation
|
|
39
|
+
|
|
40
|
+
Install the package globally via npm:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
npm install -g simceptor-cli
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Or run it directly using `npx`:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
npx simceptor-cli listen [options]
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## π Usage Guide
|
|
55
|
+
|
|
56
|
+
Run the `listen` command with your credentials to start tunneling:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
simceptor listen --token <YOUR_PERSONAL_ACCESS_TOKEN> --to http://localhost:3000 --server wss://your-simceptor-host.com
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### Options
|
|
63
|
+
|
|
64
|
+
| Flag | Type | Default | Description |
|
|
65
|
+
|---|---|---|---|
|
|
66
|
+
| `-t, --token` | `string` *(Required)* | - | Your Simceptor Personal Access Token (PAT) with `relay` scope |
|
|
67
|
+
| `-o, --to` | `string` | `http://localhost:3000` | The URL of your local running server where webhooks will be relayed |
|
|
68
|
+
| `-s, --server` | `string` | `ws://localhost:8080` | Simceptor WebSocket host server URL |
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## π Security First
|
|
73
|
+
|
|
74
|
+
- **Token-based authorization**: Tunnels are guarded by Personal Access Tokens generated in your Simceptor settings.
|
|
75
|
+
- **Scope limitation**: Generate tokens restricted strictly to the `relay` scope so they cannot be used to edit your API mocks or projects.
|
|
76
|
+
- **Secure WebSockets**: Always connect using `wss://` on production/remote hosts to encrypt token transmission and prevent MITM snooping.
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## π License
|
|
81
|
+
|
|
82
|
+
MIT License. Copyright (c) 2026. See [LICENSE](LICENSE) for details.
|