Gingee CLI: Command Reference

The gingee-cli is the official, all-in-one command-line interface for the Gingee platform. It is a powerful tool for both developers and system administrators, designed to streamline every phase of the application lifecycle, from initial project creation to ongoing production management.

Installation

The gingee-cli is designed to be installed globally on your machine, making it available everywhere. NOTE: You might need to install pre-requistes based on your setup. 

npm install -g gingee-cli

After installation, you will have access to the gingee-cli command in your terminal.

Verifying the Installation

After the installation is complete, you can verify that it was successful by running the version command:

gingee-cli --version

This should print the installed version number of the CLI.

Platform Specific Requirements

Windows

For most Windows users, no additional setup is required. The standard Node.js installer from nodejs.org includes everything you need.

macOS

macOS users need the Xcode Command Line Tools. Most developer-focused setups will already have this.

Linux (Debian/Ubuntu)

Linux systems require a C++ compiler toolchain to build some of the CLI's dependencies. You can install the necessary packages by running:

sudo apt-get update && sudo apt-get install -y build-essential python

Linux (RHEL/Fedora/CentOS)

For Red Hat-based distributions, you can install the necessary build tools with:

sudo yum groupinstall "Development Tools" && sudo yum install python3

Commands

Project Initialization

This is the main entry point for starting a new Gingee project.

init <project-name>

Scaffolds a complete, new Gingee project in a new directory. It launches an interactive wizard to guide you through the setup.

Usage:

gingee-cli init my-awesome-project

Wizard Prompts:

Local Scaffolding

These commands should be run from the root directory of an existing Gingee project.

add-app <app-name>

Scaffolds a new, working "hello world" application inside your project's web directory.

Usage:

gingee-cli add-app my-blog

Wizard Prompts:

add-script <app-name> <script-path>

Quickly creates a new server script file, pre-populated with the standard Gingee boilerplate.

Usage:

gingee-cli add-script my-blog api/posts

Creates ./web/my-blog/box/api/posts.js

Server Administration

These commands interact with the API of a live, running glade instance. They require you to be authenticated via the login command.

login [server-url]

Authenticates the CLI with a Glade admin panel and saves the session for subsequent commands.

Usage:

gingee-cli login

gingee-cli login -s http://remote-gingee:7070

Options:

logout [server-url]

Logs out of a specific Glade session by deleting the stored credentials.

Usage:

gingee-cli logout -s http://remote-gingee:7070

Options:

list-apps

Lists all applications installed on the target server.

Usage:

gingee-cli list-apps -s https://remote-gingee:7070

Options:

App Store Commands

These commands allow you to discover and install applications from a decentralized "app store," which is simply a server hosting a store.json manifest file.

list-store-apps

Fetches the manifest from a store URL and displays a list of available applications.

Usage:

gingee-cli list-store-apps -g https://my-store.example.com

Options:

install-store-app <app-name>

Initiates an interactive installation of an application from a store. The CLI will:

  1. Download the app's .gin package.
  2. Read the app's required permissions from its internal pmft.json manifest.
  3. Prompt you for consent to grant these permissions.
  4. Prompt you to configure any requirements (like database connections).
  5. Repackage the app with your configuration and securely install it on your target Gingee server.

Usage:

gingee-cli install-store-app my-blog-app -g https://my-store.example.com  -s http://<remote-gingee>

Options:

upgrade-store-app <app-name>

Initiates an interactive installation of an application from a store. The CLI will:

  1. Download the app's .gin package.
  2. Read the app's required permissions from its internal pmft.json manifest.
  3. Create the new set of permissions that are requested. (auto assigns previous version grants)
  4. Prompt you for consent to grant these permissions.
  5. Prompt you to configure any requirements (like database connections).
  6. Repackage the app with your configuration and securely install it on your target Gingee server.

Usage:

gingee-cli install-store-app my-blog-app -g https://my-store.example.com  -s http://<remote-gingee>

Options:

Application Lifecycle Management

These powerful commands allow for remote deployment and management of your applications.

Command Description
package-app Packages a live application from the server into a distributable .gin archive file.
install-app Installs a new application onto a server from a local .gin package file.
upgrade-app Upgrades an existing application on a server using a new .gin package file.
delete-app Permanently deletes an application and all its content from the server.

Common Options for Lifecycle Commands:

Example Usage:

# Upgrade the 'my-blog' app on a production server
gingee-cli upgrade-app --appName my-blog --ginPath ./builds/my-blog-v2.gin --server https://prod.server

Backup & Recovery

Commands for the disaster recovery and rollback features.

Command Description
list-app-backups Lists all available .gin backup files for an application stored on the server.
rollback-app Rolls an application back to its most recently created backup on the server.

Common Options for Recovery Commands:

Automation with Preset Files

For use in CI/CD pipelines or other automated scripts, the lifecycle commands (install-app, upgrade-app, rollback-app, delete-app) can be run in a non-interactive mode by providing a preset file using the -f, --file <path> option.

The preset file is a simple JSON file that contains the configuration for the action you want to perform. The CLI will use the values from this file instead of showing interactive prompts.

Example myapp-deploy-presets.json:

{
  "upgrade": {
    "ginPath": "./build/my-blog-app-v2.gin",
    "consent": {
      "grantPermissions": ["db", "fs", "httpclient"]
    },
    "config": {
      "db": [
        {
          "name": "main_db",
          "host": "prod-db.cluster.internal",
          "user": "prod_user",
          "password": "$DB_PASSWORD_PROD",
          "database": "blog_production"
        }
      ]
    }
  },
  "rollback": {
    "consent": {
      "grantPermissions": ["db", "fs"]
    }
  },
  "delete": {
    "confirm": true
  }
}

Security with Environment Variables: For sensitive values like passwords, you can use environment variable placeholders (a string starting with $). The CLI will automatically substitute $VAR_NAME with the value of the process.env.VAR_NAME variable at runtime.

Example Usage in a CI/CD script:

# The server URL and app name are still passed as arguments for safety
export DB_PASSWORD_PROD="a-very-secret-password"
gingee-cli upgrade-app --appName my-blog-app --serverUrl https://prod.server --file ./deploy.json

Service Management

Commands for running Gingee as a native background service. These commands must be run from a project's root directory and typically require sudo or Administrator privileges.

Local Utilities