mirror of
https://github.com/clusterio/clusterio.git
synced 2026-11-12 23:04:52 +09:00
Hornwitser
2c52c265cf
The behaviour of creating the config file if it's missing while convenient causes confusion and problems when the tools are run in the wrong folder. They end up creating a shadow installation and misdirect the user with nonsensical error messages, instead pointing to the real problem which is that the tool can't find the configuration needed to actually run. Require a config file to be present at startup and refuse to run if this file is missing. To support the odd use-case of creating the config when missing a --create-config flag is added. To conveniently generate a config file to edit out from the "config create" command is added.
113 lines
4.0 KiB
Markdown
113 lines
4.0 KiB
Markdown
# Clusterio Command Line Interface
|
|
|
|
|
|
Provides a command line interface for managing a Clusterio cluster.
|
|
|
|
Note that this document only describes the options and commands for managing clusterioctl itself, see [Managing a cluster](/docs/managing-a-cluster.md) for the available commands used for managing a cluster.
|
|
|
|
|
|
## Usage
|
|
|
|
npx clusterioctl <command>
|
|
|
|
Common options:
|
|
|
|
* `--plugin-list <file>` JSON file to use for storing the list of plugins that are available to ctl.
|
|
Defaults to `plugin-list.json` and will be created if it does not exist.
|
|
See the `plugin` command for managing this list.
|
|
|
|
* `--config <file>` JSON file to use for storing configuration for ctl.
|
|
Defaults to `config-ctl.json` and is required for operation.
|
|
See the `config` command for inspecting and modifying the configuration.
|
|
|
|
* `--create-config` If the config file is missing, create a new one and carry on instead of exiting with an error.
|
|
Alternative to the `config create` command.
|
|
|
|
|
|
### `plugin <command>`
|
|
|
|
Configure plugins available to be loaded by ctl.
|
|
The available plugins will be automatically loaded and the commands they provide will be added to the ctl utility.
|
|
|
|
|
|
#### `plugin install <package>`
|
|
|
|
Install a plugin from npm and add it to the plugin list.
|
|
The package is passed to `npm install --save` so anything npm accepts works, including a version like `@clusterio/plugin-subspace_storage@2.0.0`.
|
|
This command refuses to run outside the directory Clusterio was installed in, as the plugin has to end up in that directory's node_modules to be found.
|
|
|
|
For example, installing the Subspace Storage plugin:
|
|
|
|
npx clusterioctl plugin install @clusterio/plugin-subspace_storage
|
|
|
|
Since the `plugin-list.json` is shared between controller, host and ctl you usually only need to do this once per machine.
|
|
|
|
|
|
#### `plugin add <path>`
|
|
|
|
Add plugin either by require path or relative/absolute path to the plugin directory.
|
|
A relative path must start with ./ or ../ (or .\ and ..\ on Windows) otherwise it will be assumed to be a require path for an installed package in node_modules.
|
|
This is mainly useful for plugins under development, packages published on npm are better installed with `plugin install`.
|
|
|
|
For example, adding a plugin checked out in the external_plugins directory:
|
|
|
|
npx clusterioctl plugin add ./external_plugins/my_plugin
|
|
|
|
|
|
#### `plugin remove <name>`
|
|
|
|
Remove a plugin by its name.
|
|
This should be done before uninstalling the plugin, otherwise there will be an error when Clusterio tries to load the info from the plugin.
|
|
Removing and unistalling a plugin is usually not neccessary as the functions provided by the plugin can be disabled in the config.
|
|
|
|
For example, uninstalling the Subspace Storage plugin:
|
|
|
|
npx clusterioctl plugin remove subspace_storage
|
|
npm uninstall @clusterio/plugin-subspace_storage
|
|
|
|
Since the `plugin-list.json` is shared between controller, host and ctl you usually only need to do this once per machine.
|
|
|
|
|
|
#### `plugin list`
|
|
|
|
Lists the plugins set up to be available by name followed by path.
|
|
|
|
|
|
### `config`
|
|
|
|
Manage the ctl configuration.
|
|
This allows setting the url and token to the controller to manage.
|
|
|
|
|
|
#### `config create`
|
|
|
|
Create a new config file with the default options inserted into if it doesn't already exist.
|
|
|
|
See also the `--create-config` option.
|
|
|
|
|
|
#### `config set <config-entry> [value]`
|
|
|
|
Set a config entry to the given value.
|
|
If value is not provided the entry is set to null.
|
|
If the config entry is of type object the value must be a valid JSON serialization of an object.
|
|
|
|
See docs/configuration.md in the main repositiory for the available configuration.
|
|
|
|
|
|
#### `config show <config-entry>`
|
|
|
|
Shows the value for a single config entry.
|
|
|
|
|
|
#### `config list`
|
|
|
|
Lists up all configuration entries with their currently configured values.
|
|
|
|
|
|
## See Also
|
|
|
|
[Managing a cluster](/docs/managing-a-cluster.md) for the available commands used for managing a cluster.
|
|
|
|
[The Clusterio repository](https://github.com/clusterio/clusterio) for instructions on how to set up a cluster.
|