Your idea. Your agent.
The rest comes ready.

From an idea to a folder.

Run this in your terminal. It installs soyLI and prepares a new project with the maintained Napplet boilerplate and skills for your coding agent.

curl -fsSL https://napplet.soy/install.sh | sh -s -- new my-napplet

macOS and Linux, with Git installed. You do not need a global Bun or Node installation. Follow the installer’s PATH instruction if it prints one. System requirements and downloads.

cd my-napplet
soyli dev

Open your editor or agent in that same folder. AGENTS.md and CLAUDE.md point to the bundled skills. The preview uses the same host capabilities as the website.

Already installed? Use soyli new my-napplet. You can choose to set up an identity later and start experimenting straight away.

The everyday loop.

Keep soyli dev running while you edit. It rebuilds and reloads the preview. When you are ready to share, stop it and check your work.

soyli build
soyli run verify
soyli check

verify runs the starter’s checks. check inspects the built napplet in our host; it cannot test every interaction. Play it yourself and inspect the Listing preview too.

Run soyli run test:conformance for the starter’s upstream protocol checks. These checks complement publication validation; they do not guarantee that every interaction works on every client.

git status
git diff
soyli checkpoint "Ready to share"
soyli publish --dry-run
soyli publish

checkpoint stages your source changes and makes an ordinary Git commit. Review changed and untracked files first. It stays local until you push, propose or publish. Ordinary Git commits work too.

publish --dry-run shows the release plan and destinations. Publication requires a clean, committed tree, builds the project, checks the playable result, uploads files and source, and publishes its signed Nostr listing.

Choose who you publish as.

A creator identity is a Nostr key pair. Your npub is public; your nsec is the private key. You can create a pseudonym without adding a name, email or profile.

See or switch your identity

soyli account show
soyli account list

Copy an account ID or npub from the list and replace YOUR_ACCOUNT_ID below.

soyli account use YOUR_ACCOUNT_ID
soyli account check

Selection is shared by soyLI projects on that network. Existing projects keep their assigned creator; switching does not transfer their authorship. Switch back to that creator to release an existing project.

Create another identity

soyli account create creates a key only when no identity is selected. Otherwise it reuses the selection. The new soyli account create --new option creates and selects another key while preserving earlier accounts and backups.

Preserve your key

soyli account backup

Local signing keys live in your OS credential store. Creation also saves an unencrypted, owner-only .nsec backup outside your project and prints its path. Keep a private copy. The CLI prints the path, never the key.

soyli account export "$HOME/my-napplet-recovery.ncryptsec"

Choose a new filename; the export asks for a passphrase. Restore through soyli account import, which asks for your key or encrypted recovery text at a hidden prompt. Remote identities are backed up in the signer that holds them.

Bring an existing signer

soyli account connect

Paste a bunker link at the hidden prompt.

soyli account pair

Approve the generated connection link or QR in a NIP-46 signer.

soyli account import

Import an nsec or encrypted recovery key into your OS credential store.

Website sign-in is separate. Use the identity button to select a saved account or connect one there. It does not change soyLI’s selected creator.

Check the whole listing.

In soyli dev, switch from Play to Listing to inspect the name, description, tags, creator, cover, video and upload destinations. Edit portable metadata in napplet.json.

soyli build
soyli screenshot
soyli record

The screenshot is a PNG; the optional clip is a short, silent WebM. Both are selected in napplet.json. Review them before your next checkpoint. Existing files are preserved: use a new name such as soyli screenshot preview-2.png for another capture.

A changed build needs a fresh clip, or you can remove preview.video. Without a selected cover, publication captures one automatically. A deliberately chosen scene usually makes a better first impression.

Sounds, images, fonts and other files

Keep small assets in src/assets/ and import them through the starter’s build, for example import imageUrl from './assets/player.png?url'. CSS font URLs work too. The single-file build embeds them in the finished HTML.

Simply dropping a file next to the napplet or using a /assets/… path does not make it available after publication. Larger external resources need the supported resource/media capabilities and their declared requirements. See the asset guide for supported workflows and limits.

See where your work goes.

soyli config
soyli config init

config shows effective destinations. config init saves editable overrides in the ignored .napplet-space/project.json file; it does not upload anything. This local binding also keeps publication identity separate from shared source.

Relay

wss://relay.napplet.soy receives signed listings and metadata.

Blossom

https://blossom.napplet.soy stores HTML, source archives, covers and clips.

Git / GRASP

https://git.napplet.soy holds public source history for Git and ngit clients.

These are defaults. The optional mirrors list adds relay copies after the primary publication succeeds. You can use other compatible providers; changing an existing relay or Git repository needs an explicit migration, not just a retry with new settings.

Publication returns a portable Nostr address and a release link. To claim a readable /@handle/slug route, open your napplet page, connect its creator identity and choose Named link. The name follows later releases.

Remix first. Choose where it goes.

Use Make it yours on a napplet page for an install-and-remix command, or replace NAPPLET_LINK below with its URL.

soyli remix NAPPLET_LINK my-remix
cd my-remix
soyli setup
soyli dev

Make your changes, check them, then choose either or both paths from that same working copy.

soyli publish

Release your own napplet under your identity.

soyli propose "Describe the change"

Send changes upstream with a playable preview. Requires a Git-backed source.

Save a soyli checkpoint "Describe the change" before either action. Proposals preserve Git ancestry and use Nostr Git events, so ordinary Git/ngit tools can inspect the work. Run propose again after a new checkpoint to update the same proposal.

Review someone’s contribution

soyli review

Run this in your project. The local review app lists proposals, lets you play the original and proposed versions, inspect the diff, discuss changes and merge locally. Opening a supplied preview does not run its source build.

Merging and releasing are separate steps. soyli push shares Git state; soyli publish releases the updated napplet. The website’s Proposed changes section also lets people play and discuss a proposal. Full collaboration reference.

Shared scores and peer sessions.

soyLI includes guidance and a shared host for CVM scoreboards, matchmaking and NAP-WEBRTC peer connections. Your napplet supplies the game rules and synchronization; the host handles signaling and transport.

soyli backend init
soyli backend status

Read the generated docs/napplet-backend.md with your coding agent. Declare scoreboards and required capabilities, then use soyli dev for isolated local backend data. Preview scores do not go to the public board.

This does not deploy arbitrary server code. It provides the shared service contract described in the backend guide, including multiplayer test scenarios. Test guest responsiveness as well as connection success.

Update, diagnose, carry on.

curl -fsSL https://napplet.soy/install.sh | sh

This updates the installed CLI without creating a project. Then run soyli skills update in an existing project to refresh its bundled guidance. Edited guidance is preserved and conflicts are reported; source and dependencies are not automatically migrated.

soyli --version
soyli doctor
soyli account check
soyli --help

Publication interrupted?

Use soyli status --refresh, then soyli publish --resume to finish the saved release. Resume uploads its frozen bytes, not later edits.

Keychain unavailable?

Unlock the OS credential store. Linux needs a running Secret Service keyring; there is no plaintext signing fallback.

Pausing a project?

Save a checkpoint and keep the whole folder, including .git and the ignored .napplet-space binding and journals. Next time, run soyli dev in that folder.

Command missing?

Check the installed version and help, then update. A source checkout can contain features that have not reached the downloadable release yet.

For all flags and implementation limits, see the CLI reference. For the bigger picture, visit the About FAQ.