Deploy a Polkadot Product from your terminal with playground-cli. The pg command pairs with your Polkadot App, builds your Product, uploads the bundle, and publishes it to a DotNS name. No local host setup is required to reach a live deployment.
The CLI is the command-line counterpart to Polkadot Desktop: Desktop runs published Products by their DotNS names; pg takes a project on disk and turns it into one. By the end of this guide, you will have a Product live at its own name, reachable in any browser through the DotNS web gateway.
TestNet names end in .paseo, not .dot
DotNS top-level domains are per network. On Paseo Next v2, the TestNet the playground CLI targets by default, names are minted under .paseo: you deploy myproject57 and get myproject57.paseo, served at https://myproject57.paseo.li. Passing a name that ends in .dot is rejected with an actionable error, so pass the bare label (myproject57) and let the CLI append the environment's TLD.
Building with an AI agent?
Point your coding agent at the right skills, repos, and docs first, so it writes idiomatic Product code instead of generic boilerplate. See Set Up Your AI Agent for a paste-ready setup prompt.
Before You Start¶
Get these in order before your first deploy. The last two are easy to skip and fail silently later, so do not leave them out:
- Install the Polkadot App on your phone and create an account. It pairs with
pgand signs your deploy. - Have a terminal with
curlavailable and permission to install CLI tools in your user shell. - Have a Product project on disk with a package-manager build command.
- Fund your account with PAS from the faucet. PAS pays transaction fees and the name deposit.
- Get a Bulletin Chain storage authorization for the account that will sign. Without it, uploads are rejected at deploy time even when your balance is fine — a prerequisite that surfaces only as a failed publish. See Get TestNet Tokens.
Fund the account that actually signs
The PAS balance and the storage authorization are both per account, and the account that signs your deploy may not be the one you expect. If a deploy fails with no allowance set for account, see Accounts and Signing and the troubleshooting entry. Account mapping to an EVM address is handled for you for the product account you deploy with; a smart contract needs its signing account mapped explicitly, covered in Add a Smart Contract to Your Product.
What a first deploy costs
In one test run, taking an app live cost about 10.4 PAS: roughly 10 PAS for the name and about 0.4 PAS for a 2.6 KB upload, with each on-chain step taking around a minute. Name cost depends on length and tier, so treat these as a ballpark. On TestNet, funding is rarely the constraint.
CLI version
The CLI is in active development, and breaking changes between versions are expected. If a command below no longer matches, check this page's last update against the latest playground-cli release.
Install the CLI¶
The installer supports Linux and macOS. On Windows, work inside WSL and follow the Debian/Ubuntu steps there.
-
Install the base prerequisites. macOS needs no preparation:
curlships with the OS, and the Xcode Command Line Tools cover the rest. On a fresh Debian or Ubuntu system: -
Run the installer:
The binary lands in
~/.polkadot/bin/, with both commands symlinked into~/.local/bin/and that path appended to your shell RC file. -
Open a new shell, or
sourceyour RC file, and verify the install:
Command aliases
The installer registers two interchangeable commands: playground (canonical) and pg (short alias). This guide uses pg throughout.
Pinning a version
Pass VERSION to install a specific release, for example curl -fsSL … | VERSION=v0.47.0 bash. Later, pg update moves you to the newest release.
Log In¶
pg login is the first-run setup: it pairs the CLI with your signer, installs the toolchain, and requests your service allowances. It is safe to re-run; existing installs and sessions are detected and skipped. Do not reach for pg init here — that scaffolds a project from the starter template and pairs nothing.
Three things happen, and the first two run concurrently:
- Login: A QR code is printed to the terminal. Scan it with the Polkadot App to pair. Skipped if you already have a session under
~/.polkadot-apps/. - Toolchain install:
git,curl, a C linker,rustupwith nightly andrust-src,cargo-pvm-contract,wget, and theipfsCLI (Kubo). Existing installs are detected and skipped. - Account setup: Once a session exists, your phone shows a single approval dialog requesting the
BulletInAllowance(Bulletin uploads at deploy time) andSmartContractAllowance(which mints PGAS to yourplayground.dot/0product account and account-maps it on chain).
pg deploy needs the ipfs CLI, and pg login is what installs it
Do not skip this step. pg deploy requires the Kubo ipfs binary on your PATH; if you never log in, install it yourself with brew install ipfs or from docs.ipfs.tech/install. This is a temporary requirement while the pure-JS merkleizer is being fixed.
Signer modes
Signer choice is made at deploy time, not at login, through pg deploy --signer:
- Mobile signer (
--signer phone): Signs with the account you paired here, approving each on-chain step on your phone. Recommended for any deploy you intend to keep. - Dev-only signer (
--signer dev): No phone needed; uses shared development keys (pair it with--suri //Aliceto pin a known keypair). The deployed Product will be owned by the shared dev account, not by you.
Funding is opt-in
pg login never sends tokens. If your product account needs a testnet balance, run pg drip to top it up (1 PAS per run, up to 10 PAS, from a shared dev funder), or use the faucet. Run pg status at any time to see your product account address, its balances, and your allowance state.
Build¶
pg build auto-detects and runs your project build.
Deploy¶
pg deploy runs the full pipeline: build the frontend, upload artifacts to the Polkadot Bulletin Chain, and register a DotNS domain under the environment's TLD (.paseo on Paseo Next v2). Before building, it always runs your package manager's install step to keep dependencies in sync.
# Interactive - pg prompts for signer, domain, and build directory
pg deploy
# Dev signer - no phone needed (the deployed Product is owned by the shared dev account)
pg deploy --signer dev --suri //Alice --domain my-product
Pass the bare label to --domain. The CLI appends the environment's TLD, so my-product becomes my-product.paseo on Paseo Next v2. Name availability depends on the label's length and digit suffix; see Choose a Name for the rules the prompt enforces.
Your phone will prompt — check it
With the phone signer, each on-chain step waits for you to approve it in the Polkadot App, and no push notification announces the prompt. If the deploy seems to pause (including a deliberate ~60-second wait while your name is registered), open the app and approve the pending request. See Troubleshooting.
Note
pg deploy includes a memory watchdog that aborts the deploy if the process exceeds 4 GB RSS. If you hit this limit, set DOT_MEMORY_TRACE=1 alongside DOT_DEPLOY_VERBOSE=1 to capture per-second RSS and heap samples.
For the full interactive deploy walkthrough, including the domain-name rules, contract redeploys, and the confirmation summary, see Deploy Your App.
More CLI commands
Account and session
-
pg status: Prints your signed-in product account in both encodings (SS58 and H160), its PAS and PGAS balances, and the state of your Bulletin and smart-contract allowances. Read-only: it signs nothing and submits nothing, so it is safe to run at any time. With no session paired it prints a "log in first" notice and exits cleanly. -
pg drip: Tops up your product account with a little TestNet PAS: 1 PAS per run, up to a 10 PAS cap, from a shared dev funder rather than the public faucet. It only ever funds the caller's own account, resolved from the active session, so there is no address flag. Login never calls it for you. -
pg logout: Signs out of the paired account, tells the paired phone to drop its side of the connection, and clears session files under~/.polkadot-apps/. A no-op if you are not signed in.
Projects and deploys
-
pg init: Scaffolds a new project from the playground starter template. A shorthand forpg mod playground-template. -
pg mod: Clones a moddable app from the Playground registry so you can customize and redeploy it as your own Product. Only apps that opted into--moddableat deploy time are listed. Pass a domain label, such asmy-productormy-product.paseo, to clone directly, or omit it to open an interactive picker showing every moddable app. Source is fetched as a tarball over HTTPS, so neithergitnorghis required. -
pg decentralize: Takes a static site you already have — a live URL to mirror, or a local build directory — uploads it to the Bulletin Chain, and registers a DotNS name pointing at it. The counterpart topg deploy, which builds your project first. -
pg deploy-all: Deploys several apps listed in a JSON manifest in one invocation. Builds run in parallel, while all on-chain work is serialized per signing account so concurrent deploys never collide on a nonce. Non-interactive by design. -
pg contract: The playground-native path to contracts, backed bycdm.pg contract deploybuilds, deploys, and registers your contracts signed by your logged-in account;pg contract installwritescdm.jsonand the generated type outputs. See Add a Smart Contract to Your Product for the workflow, including when to callcdmdirectly instead. -
pg update: Updatespgto the latest version from the GitHub releases page.
Scripting a deploy, or handing one to an agent
pg deploy -y runs non-interactively using defaults, skipping every prompt. It requires --domain, and --signer defaults to dev. For full control in CI, pass --signer, --domain, --buildDir, and --playground explicitly; add --suri //Alice with --signer dev so the dev signer uses a known keypair. See Set Up Your AI Agent for orienting a coding agent around this toolchain.
You have deployed a Polkadot Product. To keep building it with your own editor and toolchain, head to the Build guides; they open with project setup so Polkadot Desktop can load your Product from localhost while you iterate with live reload.
Where to Go Next¶
-
Learn Product SDK
Understand the SDK that powers your Product: what each package does and how the pieces fit together.
-
Guide Build Guides
Set up the local dev loop, then add capabilities to your Product: signing, on-chain reads, decentralized storage, off-chain pub/sub, local persistence, and smart contracts.
-
Guide Deploy Your App
The full deploy flow in depth: build the bundle, register a DotNS name, publish to the playground, and go live on the Bulletin Chain.
Generate and publish a Polkadot Product in the browser with RevX App Builder. RevX gives you a browser-based IDE, scaffolds a Product from a natural-language prompt, and publishes it to a .dot name after you sign the final step with the Polkadot App.
This route does not require a local development environment. By the end, you will have configured an AI provider in App Builder, generated a Polkadot Product from a prompt, inspected the generated code, and published it to .dot.
Prerequisites¶
Before starting, make sure you have:
- The Polkadot App installed on your phone with an account created; it signs the final publish step.
- An API key for an AI provider supported by App Builder, such as OpenAI or Anthropic.
Open RevX¶
Open RevX in your browser. RevX is a browser-based IDE; you will use the App Builder track to scaffold a Polkadot Product end to end.
Open App Builder¶
From the sidebar, select App Builder. App Builder is RevX's track for generating Polkadot Products using AI-assisted workflows.
Create a New App¶
Click Create App to start a new project. RevX automatically installs the required dependencies and initializes the project environment so you can move straight into configuration and prompting.
After clicking Create App, you will see a loading screen while the IDE initializes the project environment.
Note
Initial setup may take a moment while dependencies install. Wait for the environment to finish initializing before configuring the builder.
Once the environment is initialized, you will see a minimal app scaffolded in the editor and running in the terminal.
Configure the Builder¶
From the App Builder view, click the Settings icon to open the AI configuration panel.
Configure the following:
- AI provider: The backend service that powers code generation.
- API key: The credential for your AI provider.
- Model: The specific model to use from the selected provider.
These settings let the IDE generate applications using the selected AI backend. You can change them at any time if you want to switch providers or models.
Generate an App¶
Use the chat interface to describe the app you want to build. RevX generates the application structure and code automatically based on your prompt.
Example prompt
Build a Product that shows the balance of Alice (a standard Substrate dev account)
After you submit the prompt, the IDE produces the project files and scaffolds the app for you to review.
Tip
Keep prompts concrete and scoped. Short, specific prompts tend to produce app structures that are easier to review and iterate on.
Inspect the Generated Code¶
Once generation completes, open the generated files in the editor to review what was produced. You can continue iterating on the application from within RevX: refine the prompt, edit code directly, or layer additional changes through the chat interface.
Publish to .dot¶
When your app is ready, click Publish to .dot to deploy the application to the Polkadot ecosystem. The publish action takes the app you generated in RevX and makes it available under a .dot name.
After clicking Start Deploy, you will be asked to sign the transaction with your Polkadot App.
After signing the transaction, you will see the deployment progress in the terminal. Your Product is now live under its .dot name. Open it in Polkadot Desktop, or on Polkadot Web at https://<name>.dot.li in any browser.
Where to Go Next¶
-
Guide Build Guides
Set up the local dev loop, then add capabilities to your Product: signing, on-chain reads, decentralized storage, off-chain pub/sub, and local persistence.
| Created: June 16, 2026