Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: add CLI documentation #63

Merged
merged 2 commits into from
Jan 5, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 90 additions & 0 deletions docs/cli.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
---
id: cli
title: CLI
sidebar_label: CLI
---

## Installation {#installation}

### Global {#installation-global}

```bash
npm install -g nodecg
```

### In project {#installation-local}

```bash
npm install -D nodecg
```

## 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/<bundleName>.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 |
2 changes: 1 addition & 1 deletion docs/creating-bundles.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 ../..
Expand Down
12 changes: 4 additions & 8 deletions docs/docker.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 ([]).
Expand All @@ -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

```

Expand Down
2 changes: 1 addition & 1 deletion docs/frameworks/typescript.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
15 changes: 6 additions & 9 deletions docs/installing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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}

Expand Down
2 changes: 1 addition & 1 deletion docs/running-nodecg.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
11 changes: 6 additions & 5 deletions sidebars.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ const sidebars: SidebarsConfig = {
'manifest',
'nodecg-configuration',
'using-npm',
'cli',
'extensions',
'bundle-configuration',
'assets',
Expand All @@ -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',
],
Expand Down
Loading