@greensecurity/apps-cli

Build, preview and publish apps for the Green Security platform. Requires Node.js 22+.

npx @greensecurity/apps-cli login                    # device-code login as yourself
npx @greensecurity/apps-cli create my-app --app-id 42
cd my-app
npx @greensecurity/apps-cli add view gs.company.vendor.detail
npx @greensecurity/apps-cli dev                      # live preview inside the Green Security app
npx @greensecurity/apps-cli build                    # dist/bundle.js + sha384 integrity
npx @greensecurity/apps-cli upload --bundle-url https://cdn.example.com/my-app/0.1.0/bundle.js

The installed binary is gs-apps; every command has --help.

Apps are built on @greensecurity/javascript-sdk >=0.46.0-0 <1.0.0 (apps/runtime's defineApp, apps/ui, apps/hooks). create --no-install works offline; if that SDK release is not on npm yet, install it from a checkout: npm install /path/to/repconnex/api-docs-sdks react react-dom.

| Command | What it does | | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | login / logout / whoami | OAuth device-code login; tokens stored in ~/.config/greensecurity/credentials.json (0600) per environment. logout revokes the login on the server | | create <name> | Scaffold an app from a template (--template, --app-id, --no-install) | | add view <surface-id> | Add a view to green-app.json and generate its component | | grant permission <resource.action> "<purpose>" | Request an API permission | | grant url <https-url/> "<purpose>" | Allow a connect-src (or --image for img-src) source | | revoke permission\|url … | Remove them again | | validate | Check the manifest (including CSP limits) and that every view is registered in defineApp({ views }) | | dev | Bundle, serve and register a dev session (--localhost, --lan, --tunnel, --tunnel-url) | | build | Production bundle; records ui_extensions.bundle.integrity | | upload | Verify the hosted bundle matches the local build, then publish the manifest | | developers list\|add\|remove | Manage the app's developers (owners only) |

Every command exits with status 0 when it succeeds and 1 when it fails, so validate and upload can gate CI. An unknown command or flag, or a flag value that can't be parsed, also exits non-zero. create uses the default template unless you pass --template.

Back-end-only apps have no views: green-app.json has no ui_extensions, and your own service calls the API with installation tokens. Create one with create <name> --template backend. For such an app:

• validate checks the manifest only.
• build says there is nothing to bundle and exits 0.
• upload posts the manifest without any bundle.
• dev refuses, because there is no UI to preview.

add view on a back-end-only app turns it into a UI app. It adds src/index.tsx, tsconfig.json and the SDK dependencies (only those missing), and it undoes all of this if any step fails.

Environment: --env local|staging|production or GREEN_SECURITY_API_URL (default production; https, or plain http only to localhost, 127.0.0.1 or [::1], since your login goes with every request). GREEN_SECURITY_WEB_URL overrides the web host used for preview links.

The login is a 15-minute access token plus a single-use refresh token. The CLI renews them when less than a minute is left, or once after a 401, so a long dev session keeps working. The login ends after 30 days without use, and at the latest 90 days after login. Renewal is serialised across concurrent gs-apps processes through a lock (one credentials.json.lock.<id> file per process): presenting a refresh token twice makes the server revoke the whole login. If a renewal's answer is lost, the CLI retries once at once with the same refresh token (the server allows that for 30 seconds); a rate-limited renewal backs off and never ends the login. A login saved by an older gs-apps, before refresh tokens, asks you to run login once more.