Command-Line Interface (CLI)

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CONTRIBUTING.md
• package.json
• src/admin-html.ts
• src/index.ts
• src/server.ts

The gr8hopper application provides a robust command-line interface for execution, configuration, and data management. The CLI is the primary method for running the service in self-hosted environments (like Docker or a VPS) and for deploying and managing it on Cloudflare Workers. It relies on a combination of npm scripts, environment variables, and direct execution via npx or node.

This document covers the different ways to interact with gr8hopper from the command line, including server execution, configuration through environment variables, and using specialized scripts for tasks like bulk data import.

Application Execution

The application can be executed in several ways depending on the target environment (Node.js/VPS vs. Cloudflare Workers) and the context (development vs. production).

Sources: package.json:8-13, README.md:290-333

Node.js / VPS Execution

For self-hosted environments, the application is started as a Node.js server. The package.json file defines a bin entry, allowing the application to be run directly using npx.

Sources: package.json:5-7, src/server.ts

The following diagram illustrates the startup sequence for the Node.js server.

This diagram shows the critical validation checks for admin credentials during the server startup process.
Sources: src/server.ts:80-130

Key Commands:

Command	Description
npm start	Runs the production-built server using node dist/server.js.
npx gr8hopper	Executes the server via the bin entry, suitable for global installations.
npm run dev:node	Starts the server in development mode with hot-reloading using tsx.
bun src/server.ts	Runs the server directly using the Bun runtime.

Sources: package.json:10-12, README.md:329-333

Cloudflare Workers Execution

For edge deployments, gr8hopper is managed using the wrangler CLI, which is orchestrated via npm scripts.

Key Commands:

Command	Description
npm run dev	Starts a local development server for Cloudflare Workers using wrangler dev.
npm run deploy	Deploys the application to the Cloudflare production environment using wrangler deploy.

Sources: package.json:9,13

Configuration via Environment Variables

Configuration is managed primarily through environment variables. This allows for flexible and secure setup across different deployment platforms like Docker, Systemd, and Cloudflare Workers.

Core Server Configuration (VPS/Docker)

When running as a Node.js server, the following environment variables are used. The server will perform a hard exit if the required ADMIN_USERNAME or ADMIN_PASSWORD variables are not set.

Variable	Default	Description	Source File
PORT	3000	The HTTP port the server listens on.	src/server.ts:74
CONFIG_FILE	./routes.json	Path to the JSON file for storing routes and settings.	src/server.ts:75
ADMIN_USERNAME	(required)	The username for accessing the admin panel.	src/server.ts:80-88
ADMIN_PASSWORD	(required)	The password for accessing the admin panel.	src/server.ts:89-97
ADMIN_PATH	admin	The URL path for the admin panel (e.g., /admin).	src/server.ts:76

For security, using the username admin is explicitly rejected, and the application will exit.
Sources: src/server.ts:104-114

Cloudflare Workers Configuration

In a Cloudflare Workers environment, configuration is provided through environment variables and secrets set via the wrangler CLI.

Variable	Type	Description	Source File
ADMIN_USERNAME	Secret	The username for the admin panel.	src/index.ts:36-39
ADMIN_PASSWORD	Secret	The password for the admin panel.	src/index.ts:40-43
ADMIN_PATH	Variable	The URL path for the admin panel.	src/index.ts:33
CLOUDFLARE_API_TOKEN	Secret	Optional API token for purging the Cloudflare cache.	src/index.ts:51-53
CLOUDFLARE_ZONE_ID	Secret	Optional Zone ID associated with the API token for cache purging.	src/index.ts:51-53

These secrets are set using the wrangler secret put command.
Sources: README.md:214-215, src/index.ts:36-43

Development Environment (.dev.vars)

For local development convenience when running in a Node.js environment, the server can automatically load environment variables from a .dev.vars file located in the project root. This behavior is handled by the loadDevVars function and is skipped if NODE_ENV is set to production.

The function parses the file, handles quoted values, and sets the variables in process.env only if they are not already set, respecting explicitly exported shell variables.

Sources: src/server.ts:12-71

Data Management Scripts

The project includes CLI scripts for managing application data, such as bulk importing routes.

Bulk Route Import (import:routes)

The npm run import:routes script provides a way to bulk import routes and settings directly into the Cloudflare KV store, bypassing the admin UI. This is useful for initial deployments, CI/CD pipelines, or migrations.

The script is defined in package.json and executes node scripts/import-routes.cjs.

Sources: package.json:15, README.md:255-261

Usage:

# Import routes.json to production KV
npm run import:routes routes.json

# Import to local dev KV
npm run import:routes routes.json --local

Sources: README.md:264-269

File Format:
The script expects a JSON file with a specific structure containing routes and optional settings objects.

{
  "routes": {
    "my-route": {
      "template": "https://example.com/product/{id}",
      "active": true,
      "passthrough": true
    }
  },
  "settings": {
    "fallback_url": "https://example.com/not-found",
    "cache_ttl": 604800,
    "route_param": "r"
  }
}

Sources: README.md:274-292

NPM Scripts Summary

The package.json file defines several scripts to streamline development, testing, building, and deployment.

Script	Command	Description
dev	wrangler dev	Runs the Cloudflare Workers development server.
dev:node	tsx watch src/server.ts	Runs the Node.js server with hot-reloading for development.
build	tsc	Compiles the TypeScript source code to JavaScript in the dist/ directory.
start	node dist/server.js	Starts the production Node.js server from the compiled output.
deploy	wrangler deploy --config wrangler.production.toml	Deploys the application to Cloudflare Workers using the production config.
import:routes	node scripts/import-routes.cjs	Executes the bulk import script for routes and settings.
lint	eslint src/ --max-warnings=0	Lints the source code for errors and style issues.
test	vitest run	Runs the test suite using Vitest.

Sources: package.json:9-19

Conclusion

The command-line interface is integral to the operation and management of gr8hopper. It provides a clear and powerful separation of concerns for different deployment targets, from local development on Node.js to production deployments on Cloudflare's edge network. Through environment variables, it offers a secure and standard way to configure the application, while npm scripts abstract away the complexities of building, running, and deploying the service.