Tutorial: Hello World

You need Shellaro 0.7, Node.js 22.13 or later, and this repository (for the CLI).

1. Create the project

node C:\path\to\shellaro\packages\cli\bin\shellaro.mjs ext create hello --publisher me
cd hello

You get:

hello/
  manifest.json        id me.hello, one command "hello" (ui.commands)
  src/extension.ts     the code
  types/shellaro.d.ts  API types
  tsconfig.json, package.json, README.md, CHANGELOG.md, .gitignore

src/extension.ts:

import { shellaro, type ExtensionContext } from "@shellaro/extension-sdk";

export function activate(context: ExtensionContext): void {
  context.subscriptions.push(
    shellaro.commands.registerCommand("hello", async () => {
      await shellaro.window.showMessage(`Hello from Hello (Shellaro ${shellaro.version})`);
      shellaro.log.info("Said hello");
    }),
  );
}

2. Run it in Shellaro

shellaro ext dev

In Shellaro: Settings > Developer > turn on Developer Mode > Load extension folder... > choose hello, approve "Add commands". Press Ctrl+Shift+P and run Hello: Say Hello.

3. Change it

Edit the message in src/extension.ts and save. ext dev rebuilds, Shellaro reloads the extension (toast: "Reloaded after a change"); run the command again.

4. Use the context

Add "context.read" to permissions in manifest.json and change the handler:

const ctx = await shellaro.context.get();
await shellaro.window.showMessage(ctx.connected ? `Connected to ${ctx.hostname} as ${ctx.user}` : "No connected terminal");

Shellaro stops the extension with Needs approval: click Approve in Settings > Developer.

5. Describe it

The Marketplace page shows README.md. Keep a How to use section with a short example (the CLI warns when it is missing). Optionally add screenshots or a short video in assets/ and list them in manifest.json:

"gallery": [
  { "path": "assets/hello.png", "caption": "The message after running Say Hello" },
  { "path": "assets/demo.mp4", "caption": "From the palette to the message (12 s)" }
]

Images up to 2 MB, videos (MP4 H.264 or WebM) up to 10 MB, at most 8 items.

6. Package and install

shellaro ext build       # me.hello-0.1.0.shellaro-ext
shellaro ext install     # Shellaro shows the review; approve it

Share the .shellaro-ext file (Marketplace > Install from file...) or publish it to your own index (shellaro ext publish --index ./my-index).

Next: the API, the sidebar template for tree views, and extensions/kubernetes for a complete extension.