V-Builder CLI

V-Builder CLI helps V-Builder widget developers manage their widgets.

Installation

npm install -g @v-one/v-builder-cli

Getting Started

Before using any commands, configure the CLI with your VONE URL:

v-builder config

Then login with your credentials:

v-builder login

You're now ready to create and upload widgets!

Available Commands

| Command | Description | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | v-builder config | Interactive configuration (prompts for VONE Url). | | v-builder config:show | Display current CLI configuration. | | v-builder login | Login to V-Builder (stores auth info locally). | | v-builder logout | Logout and clear stored authentication. | | v-builder new [widgetName] | Create a new widget (prompts for missing info). | | v-builder upload [widgetVersion] | Upload the widget. widgetVersion can be an explicit semver (e.g. 1.2.3) or one of: patch, minor, major (auto-increments current version). |

Command Details

config

v-builder config

Prompts:

• VONE Url

config:show

v-builder config:show

Shows saved configuration values.

login / logout

v-builder login
v-builder logout

Login stores credentials locally; logout removes them.

new

v-builder new
v-builder new my-widget

Prompts (if not provided via arguments / conditions):

• Widget name (if omitted)
• Category (required)

upload

# Increment patch (default if entered interactively)
v-builder upload patch

# Increment minor
v-builder upload minor

# Increment major
v-builder upload major

# Or set explicit version
v-builder upload 1.4.0

If no version argument is supplied you'll be prompted. Accepted values:

• patch | minor | major
• A valid semver version (e.g. 2.0.0)

Help

v-builder --help

Running the CLI with no arguments also shows help.

Error Handling

Non-zero exit codes on failure; unhandled promise rejections are caught and logged.

CI/CD Publishing (GitLab)

The project includes a .gitlab-ci.yml that builds on every push and provides a manual publish trigger.

Setup

1. Create an npm Access Token

   • Go to npmjs.com → click your avatar → Access Tokens → Generate New Token → Granular Access Token
   • Enter a token name
   • Tick "Bypass 2FA"
   • Under Packages and scopes, select "Read and Write"
   • Under Select packages and scopes, choose "this package" — same for organizations
   • Pick the v-one org
   • Click Generate token and copy the value

2. Add the token to GitLab

   • Go to your GitLab project → Settings → CI/CD → Variables
   • Click Add variable
   • Key: NPM_TOKEN
   • Value: paste the token
   • Check "Mask variable"
   • Click Add variable

3. Publish

   • Push your code — the build job runs automatically
   • Go to CI/CD → Pipelines → click the pipeline → click the ▶️ play button on the publish job to trigger a publish

Notes

• Interactive prompts can be cancelled (process exits).
• Ensure you are logged in before running upload.