X-Via Webgate CLI

A command line interface tool for publishing and developing applications with the Webgate platform.

Features

• Publish applications to production Webgate instances
• Development mode with automatic registration and hot-reload support
• API endpoint registration
• Docker Compose integration for local development
• TypeScript support
• Part of X-Via Core NG monorepo

Prerequisites

• Node.js (version 22.x.x)
• Yarn
• A webgate.yaml configuration file in your project
• Access to a Webgate backend instance
• Docker (optional, for development mode)

Installation

Global installation

yarn global add @xvia/webgate-cli

Usage

Development Mode

Connect your application to the Webgate portal in development mode. This command will register your app and optionally start your development server:

webgate-cli dev

Options

• -s, --script <script> - npm script to be called after successful registration
• -f, --file <configFile> - path to the webgate.yaml file (default: ./webgate.yaml)
• -e, --envFile <envFile> - path to the .env file (default: ./.env)
• -d, --down - stops the docker-compose containers

Examples

# Start development mode with default settings
webgate-cli dev

# Start development mode and run a custom script
webgate-cli dev --script "next:start"

# Use a custom config file location
webgate-cli dev --file ./config/webgate.yaml

# Stop development environment
webgate-cli dev --down

Publish Mode

Publish your application to a production Webgate instance:

webgate-cli publish

Options

• -f, --file <configFile> - path to the webgate.yaml file (default: ./webgate.yaml)
• -a, --api-only - publish only the endpoints defined in the webgate.yaml file (default: false)

Examples

# Publish full application
webgate-cli publish

# Publish only API endpoints
webgate-cli publish --api-only

# Use a custom config file location
webgate-cli publish --file ./config/webgate.yaml

Configuration

Create a webgate.yaml file in your project root with your application configuration. Refer to the Webgate documentation for the complete configuration schema.

Building the Project

From the root of the project:

yarn webgate-cli:build

Development

Testing the CLI Locally

When developing the CLI, you may want to test it locally before publishing. Due to incompatibilities between Yarn v4 (used in the monorepo) and Yarn v1 (typically used globally), use the following approach:

Option 1: Using npm pack (Alternative)

If you encounter issues with yarn link, you can use npm pack:

cd packages/webgate-cli
yarn build && npm pack && YARN_IGNORE_PATH=1 yarn unlink && YARN_IGNORE_PATH=1 yarn link

Option 2: Direct Node Execution (Quick Testing)

For quick testing without linking:

# From the webgate-cli package directory
yarn build
node lib/index.js dev
node lib/index.js publish

Unlinking After Testing

To remove the local link:

cd packages/webgate-cli
yarn unlink
YARN_IGNORE_PATH=1 yarn unlink

Running Tests

yarn test --scope=@xvia/webgate-cli

Watch Mode

yarn test:watch --scope=@xvia/webgate-cli

Linting

yarn lint --scope=@xvia/webgate-cli

Contributing

1. Create a new branch from master (eg. feature/my-new-feature)

2. Make your changes

3. Run linting and tests:

   yarn lint --scope=@xvia/webgate-cli
   yarn test --scope=@xvia/webgate-cli

4. Build the project to ensure it compiles:

   yarn webgate-cli:build

5. Commit your changes

6. Submit a pull request

Troubleshooting

• Ensure your webgate.yaml file is properly formatted and contains all required fields
• Verify that the Webgate backend is accessible from your development environment
• Check that environment variables are properly set in your .env file
• If commands are not found after global installation, ensure your global yarn bin directory is in your PATH
• For development mode issues, verify that Docker is running and accessible

License

© 2026 X-Via Tecnologia. All rights reserved

This project and all its source code are the exclusive property of X-Via Tecnologia and are protected under copyright law. No license is granted for redistribution, modification, or commercial use without express written permission from X-Via Tecnologia.