From 048b03d5cf422e941adc98e1fe17adc3626fe79a Mon Sep 17 00:00:00 2001 From: Keiichiro Amemiya Date: Thu, 2 Jan 2025 22:46:17 +0100 Subject: [PATCH 1/2] feat: add CLI documentation --- docs/cli.md | 36 +++++++++++++++++++++++++++++++++++ docs/creating-bundles.md | 2 +- docs/docker.md | 12 ++++-------- docs/frameworks/typescript.md | 2 +- docs/installing.md | 15 ++++++--------- docs/running-nodecg.md | 2 +- sidebars.ts | 11 ++++++----- 7 files changed, 55 insertions(+), 25 deletions(-) create mode 100644 docs/cli.md diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 00000000..d65ed185 --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,36 @@ +--- +id: cli +title: CLI +sidebar_label: CLI +--- + +You can install `nodecg` globally or in a project to use it as a CLI tool. + +## Installation + +### Global + +```bash +npm install -g nodecg +``` + +### In project + +```bash +npm install -D nodecg +``` + +## Usage + +- `nodecg setup [version] [--update]`, install a new instance of NodeCG. `version` is a semver range. + If `version` is not supplied, the latest release will be installed. + Enable `--update` flag to install over an existing copy of NodeCG. +- `nodecg start`, start the NodeCG instance in this directory path +- `nodecg install [repo] [--dev]`, install a bundle by cloning a git repo. + Can be a GitHub owner/repo pair (`supportclass/lfg-sublistener`) or https git url (`https://github.com/SupportClass/lfg-sublistener.git`). + If run in a bundle directory with no arguments, installs that bundle's dependencies. + Enable `--dev` flag to install the bundle's `devDependencies`. +- `nodecg uninstall `, uninstall a bundle +- `nodecg defaultconfig`, If a bundle has a `configschema.json` present in its root, this command will create a default + config file at `nodecg/cfg/:bundleName.json` with defaults based on that schema. +- `nodecg schema-types [dir]`, Generate d.ts TypeScript typedef files from Replicant schemas and configschema.json (if present) diff --git a/docs/creating-bundles.md b/docs/creating-bundles.md index db96ffd0..2e296de5 100644 --- a/docs/creating-bundles.md +++ b/docs/creating-bundles.md @@ -36,7 +36,7 @@ Before continuing, you may find it helpful to look over our [collection of simpl npm run dev ``` - Else, you can start NodeCG the old-fashioned way with `nodecg-cli`: + Else, you can start NodeCG the old-fashioned way with the CLI: ```bash cd ../.. diff --git a/docs/docker.md b/docs/docker.md index 5009a987..ce950af3 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -55,13 +55,9 @@ Example Dockerfile: ```docker # Specifies the base image to build on top of. -# This base image includes nodecg-cli, so you don't need to install it separately. # It also creates a nodecg user with appropriate permissions. FROM ghcr.io/nodecg/nodecg:latest -# Switches to the nodecg user created by the base image. -USER nodecg - # This is one way to install a bundle and generate a config for it. # You may need to take a different approach depending on your use case. # Be sure to replace [bundle-repo] and [bundle-name] with actual values and remove the brackets ([]). @@ -72,19 +68,19 @@ RUN nodecg install [bundle-repo] && nodecg defaultconfig [bundle-name] # The drawbacks are that you cannot easily change this config once it is in the container and that anyone with access to the docker image will have access to the secrets in the configuration files. # If you don't want to put your configuration inside the image, then use the volume mounting approach outlined in the Simple Deployment section above. # If you use a *.yaml or *.js config file, be sure to edit this command to reflect that. -COPY --chown=nodecg:nodecg ./cfg/nodecg.json /opt/nodecg/cfg/nodecg.json +COPY ./cfg/nodecg.json /opt/nodecg/cfg/nodecg.json # The principles outlined above apply to any file that is part of your NodeCG deployment: you can either put it in the container or you can mount it from a volume. The base nodecg/nodecg Docker image already defines volume mount points for the cfg, bundles, logs, db, and assets directories. It is recommended that you mount logs, db, and assets as volumes so that NodeCG can persist data in those folders to the host filesystem, meaning that they will be carried over when you update your Docker image and redeploy. For the cfg and bundles directories, it is up to you whether you want to bake them into your image or if you want to mount them as volumes. # This is how you'd copy a specific bundle from the build directory into your image: -COPY --chown=nodecg:nodecg ./bundles/example-bundle /opt/nodecg/bundles/example-bundle +COPY ./bundles/example-bundle /opt/nodecg/bundles/example-bundle # This is how you'd copy all bundles from the build directory into your image: -COPY --chown=nodecg:nodecg ./bundles /opt/nodecg/bundles +COPY ./bundles /opt/nodecg/bundles # This is how you'd copy all config files fmr the build directory into your image: # Again, be warned that anyone with access to this image will be able to read the secrets from these files. -COPY --chown=nodecg:nodecg ./cfg /opt/nodecg/cfg +COPY ./cfg /opt/nodecg/cfg ``` diff --git a/docs/frameworks/typescript.md b/docs/frameworks/typescript.md index c233f922..8721a7ca 100644 --- a/docs/frameworks/typescript.md +++ b/docs/frameworks/typescript.md @@ -21,7 +21,7 @@ yarn add -D typescript Optionally, you can define types of replicants using replicants' JSON schema. 1. Define schema for replicants -1. Use [`nodecg-cli`](https://github.com/nodecg/nodecg-cli)'s `nodecg schema-types` command to convert JSON schema to TypeScript type definitions +1. Use CLI's `nodecg schema-types` command to convert JSON schema to TypeScript type definitions 1. Import the type and pass it to type parameter like this: ```ts diff --git a/docs/installing.md b/docs/installing.md index 664ac093..4241cea3 100644 --- a/docs/installing.md +++ b/docs/installing.md @@ -6,14 +6,14 @@ sidebar_label: Installing ## Install {#install} -There are two methods to install NodeCG: cloning from GitHub or using the [nodecg-cli](https://github.com/nodecg/nodecg-cli). +There are two methods to install NodeCG: cloning from GitHub or using the CLI. -Install [Node.js (version 22)](http://nodejs.org/). +Install [Node.js (version 22)](http://nodejs.org/). -Using [nodecg-cli](https://github.com/nodecg/nodecg-cli): +Using the CLI: ```bash -npm install --global nodecg-cli@latest +npm install --global nodecg@latest mkdir nodecg cd nodecg nodecg setup @@ -41,12 +41,9 @@ When running NodeCG in production, [Docker](docker) or [pm2](https://github.com/ ## Installing bundles {#installing-bundles} -NodeCG's individual graphics packages are called _bundles_. They can be installed either from the command-line -(via [_nodecg-cli_](https://www.npmjs.com/package/nodecg-cli)), or by simply placing the folder into the `./bundles` directory. +NodeCG's individual graphics packages are called _bundles_. They can be installed either from the command-line (via CLI), or by simply placing the folder into the `./bundles` directory. -The easiest way to install bundles is via the command-line using [nodecg-cli](https://www.npmjs.com/package/nodecg-cli). -You will need to install [nodecg-cli](https://www.npmjs.com/package/nodecg-cli) before you can use the `nodecg` -terminal commands. +The easiest way to install bundles is via the command-line. ### GitHub {#installing-bundles-github} diff --git a/docs/running-nodecg.md b/docs/running-nodecg.md index e3b5d489..051d63e3 100644 --- a/docs/running-nodecg.md +++ b/docs/running-nodecg.md @@ -7,7 +7,7 @@ sidebar_label: Running ## Usage {#usage} - Install a bundle to the `bundles` folder. -- Start NodeCG (`node index.js` or `nodecg start` if you have [nodecg-cli](https://www.npmjs.com/package/nodecg-cli) installed). +- Start NodeCG (`node index.js` or `nodecg start` if you have installed `nodecg` globally). - Open the dashboard (`http://localhost:9090` by default). - Open a graphic from the "Graphics" menu. - You can configure NodeCG by creating and editing [cfg/nodecg.json](/docs/nodecg-configuration). diff --git a/sidebars.ts b/sidebars.ts index 27011007..17cc80d0 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -8,6 +8,7 @@ const sidebars: SidebarsConfig = { 'manifest', 'nodecg-configuration', 'using-npm', + 'cli', 'extensions', 'bundle-configuration', 'assets', @@ -18,11 +19,11 @@ const sidebars: SidebarsConfig = { 'working-on-nodecg-core', ], Advanced: [ - 'mounts', - 'security', - 'screenshot-testing', - 'custom-routes', - 'sentry', + 'mounts', + 'security', + 'screenshot-testing', + 'custom-routes', + 'sentry', 'docker', 'editing-the-database', ], From f359c9fdfefa40f18f6aa5d49a1d495184152e5e Mon Sep 17 00:00:00 2001 From: Ewan Lyon Date: Sun, 5 Jan 2025 12:34:46 +1100 Subject: [PATCH 2/2] docs: cli options as tables and add headers --- docs/cli.md | 92 ++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 73 insertions(+), 19 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index d65ed185..ad5fe4c7 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -4,33 +4,87 @@ title: CLI sidebar_label: CLI --- -You can install `nodecg` globally or in a project to use it as a CLI tool. +## Installation {#installation} -## Installation - -### Global +### Global {#installation-global} ```bash npm install -g nodecg ``` -### In project +### In project {#installation-local} ```bash npm install -D nodecg ``` -## Usage - -- `nodecg setup [version] [--update]`, install a new instance of NodeCG. `version` is a semver range. - If `version` is not supplied, the latest release will be installed. - Enable `--update` flag to install over an existing copy of NodeCG. -- `nodecg start`, start the NodeCG instance in this directory path -- `nodecg install [repo] [--dev]`, install a bundle by cloning a git repo. - Can be a GitHub owner/repo pair (`supportclass/lfg-sublistener`) or https git url (`https://github.com/SupportClass/lfg-sublistener.git`). - If run in a bundle directory with no arguments, installs that bundle's dependencies. - Enable `--dev` flag to install the bundle's `devDependencies`. -- `nodecg uninstall `, uninstall a bundle -- `nodecg defaultconfig`, If a bundle has a `configschema.json` present in its root, this command will create a default - config file at `nodecg/cfg/:bundleName.json` with defaults based on that schema. -- `nodecg schema-types [dir]`, Generate d.ts TypeScript typedef files from Replicant schemas and configschema.json (if present) +## Commands {#commands} + +### `nodecg setup [version]` {#nodecg-setup} + +```sh +mkdir nodecg +cd nodecg +nodecg setup +``` + +#### Options {#nodecg-setup-options} + +| Name | Description | +| -------------------------- | -------------------------------------------------------------------- | +| `version` | The semver version to install. If none then latest will be installed | +| `--update` `-u` | Install over an existing copy of NodeCG | +| `--skip-dependencies` `-k` | Skip installing dependencies | + +### `nodecg start` {#nodecg-start} + +Start the NodeCG instance in this directory path. + +#### Options {#nodecg-start-options} + +| Name | Description | +| ----------------------------- | -------------------------- | +| `--disable-source-maps` `-d` | Disable source map support | + +### `nodecg install [repo]` {#nodecg-install} + +Install a bundle by cloning a git repo and installing its production dependencies. +If run in a bundle directory with no arguments, installs that bundle's dependencies. + +```sh +nodecg install username/repository +``` + +#### Options {#nodecg-install-options} + +| Name | Description | +| ------------ | ----------------------------------------- | +| `repo` | A GitHub owner/repo pair or https git url | +| `--dev` `-d` | Install the bundle's `devDependencies` | + +### `nodecg uninstall [bundle]` {#nodecg-uninstall} + +Uninstalls a bundle. + +#### Options {#nodecg-uninstall-options} + +| Name | Description | +| -------------- | ----------------- | +| `bundle` | The bundle's name | +| `--force` `-f` | Ignores warnings | + +### `nodecg defaultconfig` {#nodecg-defaultconfig} + +If a bundle has a [`configschema.json`](./bundle-configuration#json-schema) present in its root, this command will create a default config file at `nodecg/cfg/.json` with defaults based on that schema. + +### `nodecg schema-types [dir]` {#nodecg-schema-types} + +Generate d.ts TypeScript typedef files from [Replicant schemas](./replicant-schemas.md) and [configschema.json](./bundle-configuration#json-schema) (if present) + +#### Options {#nodecg-schema-options} + +| Name | Default | Description | +| -------------------------- | ------- | -------------------------------------------------------------------- | +| `dir` | `schemas` | The directory where the replicant schemas are located | +| `--out-dir [path]` `-o` | `src/types/schemas` | Where to put the generated d.ts files | +| `--no-config-schema` | | Don't generate a typedef from configschema.json |