Gemigo CLI

GemiGo CLI

Overview

Use this skill when the user wants to publish an already-built static website or front-end app through the local gemigo CLI from inside NextClaw, then get a hosted public URL.

This skill is intentionally decoupled:

• The skill owns explanation, onboarding, readiness checks, workflow selection, risk disclosure, and success verification.
• The gemigo CLI owns the actual login and deployment calls to GemiGo.

From the user's point of view, the experience should feel complete:

• install or verify the local CLI,
• confirm login state against the intended origin,
• validate that the target is a built static output directory,
• create or fix gemigo.app.json,
• ask for explicit confirmation before remote write actions,
• then deploy and report the resulting hosted URL.

Do not pretend the environment is ready when it is not.

What Users Can Deploy

Use plain language with the user: this skill helps them put a finished front-end app online.

Good fits:

• a Vite, React, Vue, Svelte, Astro, or similar front-end app after it has been built into dist, build, out, or another static output directory
• a plain HTML/CSS/JavaScript page or mini app
• a landing page, portfolio page, product demo, prototype, docs site, or static dashboard
• a small browser-only tool that does not need its own server process
• a zipped or generated static folder that contains index.html

Not a fit unless the project is first converted to static output:

• a raw source repository root
• a Node/Express/Nest server app
• a Next.js app that still needs server-side rendering at runtime
• a backend API, database service, worker service, or long-running process
• anything that requires secrets or server code to run after deployment

If the user says "deploy my app" and gives you source code, first help them build it. Only deploy the generated static output folder.

Current Product Boundary

Current gemigo scope is intentionally narrow:

• generate a complete static-app manifest with gemigo init
• preflight the manifest and static output directory with gemigo validate
• log in with gemigo login
• inspect login state with gemigo whoami
• clear login state with gemigo logout
• publish a prebuilt static site directory with gemigo deploy or gemigo publish

Do not claim that gemigo can currently:

• install project dependencies,
• infer build commands automatically without inspection,
• build the app for the user without running a real build command,
• deploy server-side code,
• or publish a raw source repository root that has not been built.
• infer rich app metadata beyond the explicit gemigo init defaults and provided flags.

The safe rule is simple:

• build first,
• validate locally,
• deploy the generated static output second.

Install Boundary: NextClaw Skill vs Local CLI

Always distinguish these two layers:

• NextClaw marketplace skill install: the selectable skill exists at <workspace>/skills/gemigo-cli/SKILL.md
• Local GemiGo CLI install: the gemigo binary exists on the user's machine

Installing this marketplace skill does not automatically install the gemigo binary. If the user wants to actually publish an app, both layers must be ready.

Default NextClaw workspace:

~/.nextclaw/workspace

Typical installed skill path:

~/.nextclaw/workspace/skills/gemigo-cli/SKILL.md

Install the local CLI with:

npm install -g gemigo

Deterministic Workflow

When the user asks to publish a static app with GemiGo, follow this order and do not skip steps.

Step 0: Classify the request

Classify the task into one of these:

• install or verify gemigo,
• log in or inspect login state,
• create, validate, or fix gemigo.app.json,
• deploy a built static directory,
• troubleshoot a failed deployment.

If the user gives you a source repository instead of a built output directory, treat the build step as separate preparation work before deploy.

Step 1: Verify the local CLI binary

Run:

command -v gemigo

If missing, explain that the local CLI must be installed first:

npm install -g gemigo

Only after the binary exists should you continue to auth or deploy steps.

Step 2: Verify current login state against the intended origin

Default origin:

https://gemigo.io

Run:

gemigo whoami --origin https://gemigo.io

Interpret the result literally:

• success with a user identity: login is ready for that origin
• No saved session found: the user has not logged in on this machine yet
• Stored session is for ...: the saved login is for a different origin
• Saved session is no longer valid: the session expired and login must be redone

Do not continue to deploy if whoami is not healthy.

Step 3: Log in when needed

Default login:

gemigo login

Provider-specific login:

gemigo login --provider github
gemigo login --provider google

Remote or no-auto-open flow:

gemigo login --no-browser

Important behavior:

• the CLI may open a browser automatically,
• --no-browser prints the login URL instead,
• the saved session is origin-specific,
• if origin changes, the user must log in again for that origin.

After login, rerun:

gemigo whoami --origin <origin>

Only a successful whoami counts as readiness.

Step 4: Validate the deployment target

The target must be a built static output directory, not the source repo root.

Required shape:

• index.html exists at the directory root
• there is no top-level package.json

Observable checks:

test -f <dir>/index.html
test ! -f <dir>/package.json

If the user only gave you source code:

1. detect the framework and build command
2. run the real build
3. locate the generated output directory such as dist, build, or another static export folder
4. validate that output directory before deploy

Do not deploy the repo root just because it is the most obvious path.

Step 5: Create or fix gemigo.app.json

Create the manifest in the project root or pass a custom path with --config.

Preferred path:

gemigo init <dir> --config ./gemigo.app.json --name "My App" --description "A short app description."
gemigo validate <dir> --config ./gemigo.app.json

Use gemigo init instead of hand-writing the manifest from memory when the local CLI supports it. Use gemigo validate before deploy; do not use gemigo deploy as the first schema checker.

Required fields:

• visibility
• category
• tags
• defaultLocale
• locales
• locales[defaultLocale].name
• locales[defaultLocale].description

Useful optional fields:

• sourceDir
• slug
• extra locale entries such as zh-CN

Portable example:

{
  "$schema": "https://gemigo.io/schema/gemigo.app.schema.json",
  "sourceDir": "./dist",
  "slug": "my-static-app",
  "visibility": "public",
  "category": "Tools",
  "tags": ["static", "demo"],
  "defaultLocale": "en",
  "locales": {
    "en": {
      "name": "My Static App",
      "description": "A static app published to GemiGo."
    },
    "zh-CN": {
      "name": "我的静态应用",
      "description": "一个发布到 GemiGo 的静态应用。"
    }
  }
}

If the manifest is incomplete or invalid, fix it before deploy instead of letting the user hit a later failure.

For older local CLI versions that do not support init or validate, fall back to the portable example above, then upgrade the local CLI when possible.