cli/README.md

91 lines
3.9 KiB
Markdown

# Squeebot CLI
This package provides the runtime and tooling for Squeebot 3.x.x!
This package provides two binaries via npm: `squeebot` and `squeebotd`.
## Running Squeebot
1. Create an environment: `$ squeebot new <name> [<path>]`
2. Execute the environment in interactive mode using `squeebotd`: `$ squeebotd -i <path>/<name>.json`
3. Install plugins (documented below)
`squeebotd` just takes the path to the generated json file and creates all other necessary files and directories by itself.
The primary configuration will be located in `<path>/configs/squeebot.json`.
## Installing plugins
In order to install plugins, you have to add a repository. Repositories are JSON files served over HTTP.
For example, installing core plugins (Interactive mode `-i` on `squeebotd`):
1. `repository install https://squeebot.lunasqu.ee/pkg/plugins-core/repository.json`
2. `plugin install control simplecommands`
3. `plugin list`
## Interactive mode commands
The following commands are available when starting in interactive mode:
* `repository help` - Repository management commands
* `plugin help` - Plugin management commands
* `channel help` - Channel management commands
* `quit` - Exit Squeebot
* `inspector` - Enter JavaScript REPL (basically the same as running `node` without arguments)
## Creating a repository
In order to create a repository, you need to do the following:
1. Create a new repository: `$ squeebot repository new <name> [<path>]`
2. Build your new repository: `$ squeebot repository build <path>`
3. Your built plugins, both archived and unarchived, are in `<path>/.out`.
Repositories are created with a TypeScript build environment by default. If you do not wish to use TypeScript (not recommended) for your plugins,
add the `-t` flag to `squeebot repository new` command.
The build command supports a `-w` argument which will execute the entire build command again when you make changes (watch mode).
**Including deployments, if `-d` is present!**
### Creating plugins
Within your new repository, each directory you make will be a plugin. The plugin **must** contain the following:
1. `plugin.json` - Manifest for your plugin.
2. `plugin.js` - Has to be a JavaScript file which exports a class inherited from `Plugin` at `@squeebot/core/lib/plugin`.
3. `schema.json` - (optionally) include a JSON schema for the plugin's configuration.
**Note:** `plugin.js` only has to exist in the distribution, so `.ts` is fine, but you **have** to use `$ squeebot repository build <path>`
to build them into JavaScript files.
Plugin manifest (`plugin.json`) example:
```
{
"name": "plugin-name", // The name of your plugin, must match the name of the directory
"version": "0.0.0", // The version of your plugin, must be semantic versioning!
"description": "", // Optional description for this plugin
"tags": [], // Optional list of tags describing this plugin
"dependencies": [], // List of plugins this plugin depends on
"npmDependencies": [], // List of npm modules this plugin depends on. Supports versions, example 'thing@1.0.0'
}
```
### Deploying the repository
You can configure deployment options using a file called `deployment.json` in your repository root.
In order to activate your configured deployment, use the `-d` flag when building your repository. `-o` flag skips build and deploys immediately.
#### Development
```
{
"devSqueebot": "<full path to environment>.json",
}
```
Use `-d dev` to deploy this.
#### SSH deployment
```
{
"prod": {
"ssh": true,
"key": "<path to id_rsa>",
"host": "<ssh host>",
"user": "<ssh user>",
"target": "<full remote path>"
}
}
```
## Official repositories
All official repositories [are here](https://gitlab.icynet.eu/Squeebot/official-plugins). Production-ready builds are available to download via Squeebot CLI from `https://squeebot.lunasqu.ee/pkg/<repo name>/repository.json` by using the `repository install` command.