Skip to content

Commit 4449192

Browse files
committed
docs: Update readme
1 parent 89379d3 commit 4449192

1 file changed

Lines changed: 73 additions & 60 deletions

File tree

‎README.md‎

Lines changed: 73 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -29,71 +29,96 @@
2929

3030
## Usage
3131

32-
### Get started
33-
34-
```bash
35-
pnpm dlx paraspell-cli@latest
36-
```
32+
> [!NOTE]
33+
> Requires Node.js 24 or newer.
3734
38-
The wizard collects your choices, previews the configuration, then creates the
39-
project and installs its dependencies.
35+
### Quick start
4036

4137
```bash
42-
cd my-xcm-app
43-
pnpm dev
38+
pnpm dlx paraspell-cli@latest
4439
```
4540

46-
Use npm, Yarn, or Bun if that's your package manager:
41+
Use npm, Yarn, or Bun instead if that's your package manager:
4742

4843
```bash
4944
npx paraspell-cli@latest
5045
yarn dlx paraspell-cli@latest
5146
bunx paraspell-cli@latest
5247
```
5348

49+
### Interactive mode
50+
51+
1. Choose XCM SDK or XCM API.
52+
2. Choose React, Vue, or Node.js.
53+
3. Pick a Polkadot client for the SDK: PAPI (recommended), Polkadot.js, or
54+
Dedot.
55+
4. Choose the Swap, EVM, and Snowbridge extensions.
56+
5. Name the project and choose a package manager.
57+
6. Optionally configure a development wallet for Node.js.
58+
7. Review the configuration before files are written.
59+
5460
> [!NOTE]
55-
> Requires Node.js 24 or newer.
61+
> Project creation and dependency installation report live progress. If
62+
> installation fails, the generated project is kept and the CLI prints the
63+
> command to finish it manually.
5664
57-
### XCM SDK
65+
### What to choose 🧰
5866

59-
Call ParaSpell directly from your app. Choose a Polkadot client — PAPI
60-
(recommended), Polkadot.js, or Dedot — and generate a React, Vue, or Node.js
61-
project.
67+
| Choice | Options | Pick based on |
68+
| ------------------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
69+
| Tool | XCM SDK / XCM API | XCM SDK calls ParaSpell directly from your app. XCM API builds transfers via REST while you sign them locally, keeping XCM logic out of your app. |
70+
| Extensions | EVM, Swap, Snowbridge | **EVM** for EVM-chain origins, **Swap** for cross-chain swaps (`@paraspell/swap`), **Snowbridge** for Ethereum ↔ Polkadot transfers. |
71+
| Wallet secrets (Node.js only) | Configure / skip | Configure a development wallet (e.g. `//Alice`) so the generated server can sign and submit live transfers on `POST /`; skip it to wire up signing yourself. Secrets are entered via masked prompts and written to a gitignored `.env`. |
6272

63-
### XCM API
73+
> [!WARNING]
74+
> Avoid typing secrets literally when passing them as flags in shared shells
75+
> or CI logs: command-line values can be saved in shell history. Prefer the
76+
> interactive prompt, or edit `.env` directly.
6477
65-
A REST API that builds XCM transfers while you sign them locally, so XCM
66-
logic stays out of your app. Generate a React, Vue, or Node.js project that
67-
calls it.
78+
### Getting help
6879

69-
### Extensions
80+
```bash
81+
npx paraspell-cli@latest --help
82+
npx paraspell-cli@latest sdk --help
83+
npx paraspell-cli@latest api --help
84+
```
7085

71-
Every generated app ships with a transfer flow already wired up. Add any of
72-
these when you need them:
86+
> [!NOTE]
87+
> These commands run the CLI once without installing it, so `paraspell-cli`
88+
> alone won't work afterward. Install it globally with `npm i -g
89+
> paraspell-cli` to call `paraspell-cli --help` directly.
7390
74-
- **EVM** — use EVM chains as origins
75-
- **Swap** — cross-chain swaps via `@paraspell/swap`
76-
- **Snowbridge** — transfers between Ethereum and Polkadot
91+
Want to skip the prompts and generate a project in one command? See
92+
[Commands](#commands) below.
7793

78-
React and Vue projects generate a Vite app with wallet integration. Node.js
79-
projects generate a headless Express server with an optional development
80-
wallet.
94+
### Commands
8195

82-
### The wizard
96+
Every wizard step is also available as a flag. Pass everything a command
97+
needs and the wizard is skipped entirely, or leave a value out and the CLI
98+
only prompts for that one — handy for templates, CI pipelines, or repeated
99+
scaffolding.
83100

84-
1. Choose XCM SDK or XCM API.
85-
2. Choose React, Vue, or Node.js.
86-
3. Pick a Polkadot client for the SDK.
87-
4. Choose the Swap, EVM, and Snowbridge extensions.
88-
5. Name the project and choose a package manager.
89-
6. Optionally configure a development wallet for Node.js.
90-
7. Review the configuration before files are written.
101+
```bash
102+
paraspell-cli sdk [framework] [flags]
103+
paraspell-cli api [framework] [flags]
104+
```
91105

92-
Project creation and dependency installation report live progress. If
93-
installation fails, the generated project is kept and the CLI prints the
94-
command to finish manually.
106+
`framework` can also be passed positionally instead of via `--framework`.
95107

96-
### Scripting
108+
### Flags
109+
110+
| Flag | Values | Description |
111+
| ------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------ |
112+
| `--name` | string | Project name |
113+
| `--framework` | `react` \| `vue` \| `node` | Target framework (default `react`) |
114+
| `--client` | `papi` \| `pjs` \| `dedot` | JS client, `sdk` command only (default `papi`) |
115+
| `--extensions` | comma-separated list of `evm`, `swap`, `snowbridge` | Extensions to include |
116+
| `--package-manager` | `npm` \| `yarn` \| `pnpm` \| `bun` | Package manager used to install dependencies (default `pnpm`) |
117+
| `--out` | path | Output directory |
118+
| `--private-key` | string | EVM wallet key for the Node.js server, when using EVM or Snowbridge origins |
119+
| `--substrate-mnemonic` | string | Substrate mnemonic or `//Dev` URI for the Node.js server |
120+
121+
### Examples
97122

98123
```bash
99124
# React app using the XCM SDK and PAPI
@@ -115,28 +140,16 @@ npx paraspell-cli@latest sdk node \
115140
--extensions swap
116141
```
117142

118-
Non-interactive environments use sensible defaults; dependency installation
119-
stays an explicit CI step.
120-
121-
```bash
122-
paraspell-cli --help
123-
paraspell-cli sdk --help
124-
paraspell-cli api --help
125-
```
126-
127-
### Wallet secrets
128-
129-
Node.js projects can write a Substrate mnemonic and an EVM private key to the
130-
generated `.env`. Wallet setup is optional, values are entered through masked
131-
prompts, and `.env` is gitignored.
132-
133-
Use a development account such as `//Alice`. The generated Node.js server
134-
signs and submits live XCM transfers on `POST /`.
143+
> [!NOTE]
144+
> Non-interactive environments use sensible defaults for anything not passed
145+
> as a flag. Dependency installation stays an explicit step, so it can be run
146+
> separately in CI.
135147
136148
> [!WARNING]
137-
> Avoid secret flags in shared shells or CI logs — command-line values can be
138-
> saved in shell history. Prefer the interactive prompt, or edit `.env`
139-
> directly.
149+
> Avoid typing `--private-key` or `--substrate-mnemonic` literally in shared
150+
> shells or CI logs: command-line values can end up in shell history. Pass
151+
> them via an environment variable instead. Preferably through the
152+
> interactive prompt, or edit the generated `.env` directly.
140153
141154
## Development
142155

0 commit comments

Comments
 (0)