@hsuite/smart-engines-cli

hsuite — the developer bootstrap CLI for Smart Engines V3. Three commands that take you from "empty directory" to "smart-app running against the live testnet cluster" in under a minute.

npm install -g @hsuite/smart-engines-cli

hsuite init                    # XRPL wallet + faucet + .env.local
hsuite subscribe --env <file>  # free_testnet smart-app registration on cluster
hsuite deploy --manifest <f>   # deploy a smart-app from a JSON manifest

XRPL-only. The CLI generates an XRPL keypair, funds it via the testnet faucet, and uses it for Web3 challenge-response auth against the cluster. No Hedera credentials needed — the cluster's validator/host pods pay their own HCS fees.

hsuite init

Generate a fresh XRPL testnet wallet, fund it (~1000 testnet XRP via the official Ripple faucet), and write an .env.local with everything the showcase smart-app expects.

hsuite init                                # writes ./.env.local (testnet)
hsuite init --out smart-app/.env.local     # custom output path
hsuite init --network devnet               # devnet faucet instead
hsuite init --no-fund                      # generate wallet only, skip faucet
hsuite init --force                        # overwrite an existing .env.local
hsuite init --gateway https://...          # override the cluster gateway URL

The generated .env.local:

APP_ID=smart-app-showcase-local
APP_NAME=Smart App Showcase (local)

VALIDATOR_URL=https://v3-testnet-gateway.hsuite.network
SMART_HOST_URL=https://v3-testnet-gateway.hsuite.network

XRPL_NETWORK=testnet
XRPL_ADDRESS=r...
XRPL_PUBLIC_KEY=...
XRPL_SEED=s...                  # ⚠️ DO NOT COMMIT

# NestJS dev config
NODE_ENV=development
PORT=3000
API_KEY_ENABLED=false
CORS_ORIGINS=http://localhost:8101,http://localhost:8100,http://localhost:4200
...

# Subscription — run `hsuite subscribe` to register a free_testnet smart-app
SKIP_SUBSCRIPTION_CHECK=true
SUBSCRIPTION_TIER=free_testnet
# SUBSCRIPTION_APP_ID=          # populated by `hsuite subscribe`

hsuite subscribe

Register a free_testnet smart-app on the cluster. On testnet, the validator explicitly skips the deposit/NFT gate — DKG runs, the smart-app goes ACTIVE immediately, and the cluster-issued appId becomes your smart-app's on-chain identity.

hsuite subscribe --env .env.local
hsuite subscribe --env .env.local --name "My Smart App"
hsuite subscribe --env .env.local --services database,storage,messaging
hsuite subscribe --env .env.local --gateway https://my-cluster.example.com

Flow:

1. Reads XRPL_* + APP_NAME from .env.local
2. Builds a signer using ripple-keypairs.sign
3. Authenticates via BaasClient.authenticate({chain: 'xrpl', ...}) against the cluster
4. Calls BaasClient.deployment.init({name, port, services}) — the new four-step deploy flow's step 1 (legacy register() removed in PR-A); the cluster runs the per-entity DKG ceremony and returns the DKG entityId as appId
5. Appends SUBSCRIPTION_APP_ID=<appId> and APP_ID=<appId> to your .env.local, flips SKIP_SUBSCRIPTION_CHECK=false

After this, your smart-app boots in cluster-mode automatically.

hsuite deploy

Deploy a smart-app image from a JSON manifest via the SDK's four-step runtime-orchestration flow (init → docker push → optional uploadFrontend → deploy). Use this for CI pipelines that ship a container image to the cluster.

hsuite deploy --manifest ./my-app.json --env .env.local
hsuite deploy --manifest ./my-app.json --env .env.local --non-interactive   # for CI

my-app.json:

{
  "name": "my-smart-app",
  "port": 3000,
  "tag": "v1",
  "replicas": 1,
  "services": ["database", "storage", "messaging", "functions"],
  "env": { "NODE_ENV": "production" },
  "frontend": { "bundlePath": "./dist/bundle.tar.gz" }
}

What the command does, in order:

1. deployment.init — cluster allocates the appId (per-entity DKG entityId) and returns ephemeral DOCR push credentials.
2. (out-of-band) the CLI prints the docker login + docker push commands and waits for Enter (skipped with --non-interactive, CI=true, or no TTY — the caller is assumed to have completed the push).
3. deployment.uploadFrontend — if frontend.bundlePath is set, the tarball is uploaded.
4. deployment.deploy — the cluster reconciles the requested tag
   • replicas + env to k8s.

The returned appId is appended to .env.local as DEPLOYED_APP_ID.

End-to-end (1-minute bootstrap)

mkdir my-smart-app && cd my-smart-app
npm install -g @hsuite/smart-engines-cli

hsuite init                                  # → .env.local with funded XRPL wallet
hsuite subscribe --env .env.local            # → free_testnet appId on cluster
cat .env.local | grep XRPL_ADDRESS           # → your wallet address
cat .env.local | grep SUBSCRIPTION_APP_ID    # → your smart-app's DKG entity ID

That's it — you now have:

• A funded XRPL testnet wallet
• A registered smart-app on the live Smart Engines V3 testnet cluster
• An .env.local your NestJS backend can consume directly

What the CLI does NOT do

• Pay HCS fees. The cluster's validator/host pods do that from their own pod-local Hedera operator accounts. The smart-app never sees Hedera credentials.
• Mint a subscription NFT for free_testnet. The validator's smart-app service explicitly skips this gate on testnet — the DKG entity ID IS the on-chain registration proof. Paid-tier NFT minting is a separate post-launch flow.
• Configure your smart-app's business logic. If your smart-app does Hedera-side or Solana-side or any other-chain ops as part of its app logic, that's separate from the dev wallet and you configure it in your app's own code/env.

Use programmatically

Each command is exported for scripting:

import { initWallet, subscribeFreeTestnet, deploySmartApp } from '@hsuite/smart-engines-cli';

await initWallet({
  out: '.env.local',
  network: 'testnet',
  gateway: 'https://v3-testnet-gateway.hsuite.network',
  fund: true,
});

await subscribeFreeTestnet({
  env: '.env.local',
  gateway: 'https://v3-testnet-gateway.hsuite.network',
  services: 'database,storage,messaging,functions',
});

Companion packages

• @hsuite/smart-engines-sdk — the underlying SDK that hsuite wraps. Use it directly when you need finer-grained control over auth, BaaS calls, or chain operations.
• hsuite-ecosystem/apps/showcase — a reference NestJS backend + Ionic dApp that demonstrate the full integration. Fork it as a starting point.

Peer dependencies

| Package | Why | |---|---| | @hsuite/smart-engines-sdk | Auth + BaaS API surface | | xrpl | XRPL keypair generation + signing | | commander, chalk, ora, dotenv, uuid | CLI ergonomics (UI + env parsing) |

All bundled — npm install -g @hsuite/smart-engines-cli pulls everything.

License

MIT.