From 44f96dbd98c577b9196100d82b6971202f842f89 Mon Sep 17 00:00:00 2001 From: spinframeworkbot <202838904+spinframeworkbot@users.noreply.github.com> Date: Thu, 3 Apr 2025 01:57:17 +0000 Subject: [PATCH] Update Spin CLI reference to latest Signed-off-by: spinframeworkbot <202838904+spinframeworkbot@users.noreply.github.com> --- content/v3/cli-reference.md | 617 ++++++++++++++++++++++++++++++++++++ 1 file changed, 617 insertions(+) create mode 100644 content/v3/cli-reference.md diff --git a/content/v3/cli-reference.md b/content/v3/cli-reference.md new file mode 100644 index 00000000..de1e32bf --- /dev/null +++ b/content/v3/cli-reference.md @@ -0,0 +1,617 @@ +title = "Command Line Reference" +template = "main" +date = "2025-01-01T00:00:01Z" +[extra] +url = "https://github.com/spinframework/spin-docs/blob/main/content/v3/cli-reference.md" + +--- +# Command-Line Help for `spin` + +This document contains the help content for the `spin` command-line program. + +**Command Overview:** + +* [`spin`↴](#spin) +* [`spin add`↴](#spin-add) +* [`spin build`↴](#spin-build) +* [`spin deploy`↴](#spin-deploy) +* [`spin doctor`↴](#spin-doctor) +* [`spin login`↴](#spin-login) +* [`spin new`↴](#spin-new) +* [`spin plugins`↴](#spin-plugins) +* [`spin plugins install`↴](#spin-plugins-install) +* [`spin plugins list`↴](#spin-plugins-list) +* [`spin plugins search`↴](#spin-plugins-search) +* [`spin plugins show`↴](#spin-plugins-show) +* [`spin plugins uninstall`↴](#spin-plugins-uninstall) +* [`spin plugins update`↴](#spin-plugins-update) +* [`spin plugins upgrade`↴](#spin-plugins-upgrade) +* [`spin registry`↴](#spin-registry) +* [`spin registry login`↴](#spin-registry-login) +* [`spin registry pull`↴](#spin-registry-pull) +* [`spin registry push`↴](#spin-registry-push) +* [`spin templates`↴](#spin-templates) +* [`spin templates install`↴](#spin-templates-install) +* [`spin templates list`↴](#spin-templates-list) +* [`spin templates uninstall`↴](#spin-templates-uninstall) +* [`spin templates upgrade`↴](#spin-templates-upgrade) +* [`spin up`↴](#spin-up) +* [`spin watch`↴](#spin-watch) + +## `spin` + +The Spin CLI + +**Usage:** `USAGE: + spin ` + +###### **Subcommands:** + +* `add` — Scaffold a new component into an existing application +* `build` — Build the Spin application +* `deploy` — Package and upload an application to the Fermyon Cloud. +* `doctor` — Detect and fix problems with Spin applications +* `login` — Log into the Fermyon Cloud. +* `new` — Scaffold a new application based on a template +* `plugins` — Install/uninstall Spin plugins +* `registry` — Commands for working with OCI registries to distribute applications +* `templates` — Commands for working with WebAssembly component templates +* `up` — Start the Spin application +* `watch` — Build and run the Spin application, rebuilding and restarting it when files change + +###### **Options:** + +* `--help ` — Print help information +* `--version ` — Print version information + + + +## `spin add` + +Scaffold a new component into an existing application + +**Usage:** `spin USAGE: + add [OPTIONS] [NAME]` + +###### **Arguments:** + +* `` — The name of the new application or component +* `` — The name of the new application or component. If present, `name` is instead treated as the template ID. This provides backward compatibility with Spin 1.x syntax, so that existing content continues to work + +###### **Options:** + +* `-a`, `--accept-defaults ` — An optional argument that allows to skip prompts for the manifest file by accepting the defaults if available on the template +* `--allow-overwrite ` — If the output directory already contains files, generate the new files into it without confirming, overwriting any existing files with the same names +* `-f`, `--file ` — Path to spin.toml +* `--help ` — Print help information +* `--init ` — Create the new application or component in the current directory +* `--no-vcs ` — An optional argument that allows to skip creating .gitignore +* `-o`, `--output ` — The directory in which to create the new application or component. The default is the name argument +* `-t`, `--template ` — The template from which to create the new application or component. Run `spin templates list` to see available options +* `--tag ` — Filter templates to select by tags +* `-v`, `--value ` — Parameter values to be passed to the template (in name=value format) +* `--values-file ` — A TOML file which contains parameter values in name = "value" format. Parameters passed as CLI option overwrite parameters specified in the file +* `--version ` — Print version information + + + +## `spin build` + +Build the Spin application + +**Usage:** `spin USAGE: + build [OPTIONS] [--] [UP_ARGS]...` + +###### **Arguments:** + +* `` + +###### **Options:** + +* `-c`, `--component-id ` — Component ID to build. This can be specified multiple times. The default is all components +* `-f`, `--from ` — The application to build. This may be a manifest (spin.toml) file, or a directory containing a spin.toml file. If omitted, it defaults to "spin.toml" +* `--help ` — Print help information +* `-u`, `--up ` — Run the application after building +* `--version ` — Print version information + + + +## `spin deploy` + +Package and upload an application to the Fermyon Cloud. + +**Usage:** `spin USAGE: + deploy` + +###### **Arguments:** + +* `` — All args to be passed through to the plugin + +###### **Options:** + +* `--help ` — Print help information +* `--version ` — Print version information + + + +## `spin doctor` + +Detect and fix problems with Spin applications + +**Usage:** `spin USAGE: + doctor [OPTIONS]` + +###### **Options:** + +* `-f`, `--from ` — The application to check. This may be a manifest (spin.toml) file, or a directory containing a spin.toml file. If omitted, it defaults to "spin.toml" +* `--help ` — Print help information +* `--version ` — Print version information + + + +## `spin login` + +Log into the Fermyon Cloud. + +**Usage:** `spin USAGE: + login` + +###### **Arguments:** + +* `` — All args to be passed through to the plugin + +###### **Options:** + +* `--help ` — Print help information +* `--version ` — Print version information + + + +## `spin new` + +Scaffold a new application based on a template + +**Usage:** `spin USAGE: + new [OPTIONS] [NAME]` + +###### **Arguments:** + +* `` — The name of the new application or component +* `` — The name of the new application or component. If present, `name` is instead treated as the template ID. This provides backward compatibility with Spin 1.x syntax, so that existing content continues to work + +###### **Options:** + +* `-a`, `--accept-defaults ` — An optional argument that allows to skip prompts for the manifest file by accepting the defaults if available on the template +* `--allow-overwrite ` — If the output directory already contains files, generate the new files into it without confirming, overwriting any existing files with the same names +* `--help ` — Print help information +* `--init ` — Create the new application or component in the current directory +* `--no-vcs ` — An optional argument that allows to skip creating .gitignore +* `-o`, `--output ` — The directory in which to create the new application or component. The default is the name argument +* `-t`, `--template ` — The template from which to create the new application or component. Run `spin templates list` to see available options +* `--tag ` — Filter templates to select by tags +* `-v`, `--value ` — Parameter values to be passed to the template (in name=value format) +* `--values-file ` — A TOML file which contains parameter values in name = "value" format. Parameters passed as CLI option overwrite parameters specified in the file +* `--version ` — Print version information + + + +## `spin plugins` + +Install/uninstall Spin plugins + +**Usage:** `spin USAGE: + plugins ` + +###### **Subcommands:** + +* `install` — Install plugin from a manifest +* `list` — List available or installed plugins +* `search` — Search for plugins by name +* `show` — Print information about a plugin +* `uninstall` — Remove a plugin from your installation +* `update` — Fetch the latest Spin plugins from the spin-plugins repository +* `upgrade` — Upgrade one or all plugins + +###### **Options:** + +* `--help ` — Print help information +* `--version ` — Print version information + + + +## `spin plugins install` + +Install plugin from a manifest. + +The binary file and manifest of the plugin is copied to the local Spin plugins directory. + +**Usage:** `spin plugins USAGE: + install [OPTIONS] [PLUGIN_NAME]` + +###### **Arguments:** + +* `` — Name of Spin plugin + +###### **Options:** + +* `--auth-header-value ` — Provide the value for the authorization header to be able to install a plugin from a private repository. (e.g) --auth-header-value "Bearer " +* `-f`, `--file ` — Path to local plugin manifest +* `--help ` — Print help information +* `--override-compatibility-check ` — Overrides a failed compatibility check of the plugin with the current version of Spin +* `-u`, `--url ` — URL of remote plugin manifest to install +* `-v`, `--version ` — Specific version of a plugin to be install from the centralized plugins repository +* `--version ` — Print version information +* `-y`, `--yes ` — Skips prompt to accept the installation of the plugin + + + +## `spin plugins list` + +List available or installed plugins + +**Usage:** `spin plugins USAGE: + list [OPTIONS]` + +###### **Options:** + +* `--all ` — List all versions of plugins. This is the default behaviour +* `--filter ` — Filter the list to plugins containing this string +* `--format ` — The format in which to list the templates + + Default value: `plain` + + Possible values: `plain`, `json` + +* `--help ` — Print help information +* `--installed ` — List only installed plugins +* `--summary ` — List latest and installed versions of plugins +* `--version ` — Print version information + + + +## `spin plugins search` + +Search for plugins by name + +**Usage:** `spin plugins USAGE: + search [OPTIONS] [FILTER]` + +###### **Arguments:** + +* `` — The text to search for. If omitted, all plugins are returned + +###### **Options:** + +* `--format ` — The format in which to list the plugins + + Default value: `plain` + + Possible values: `plain`, `json` + +* `--help ` — Print help information +* `--version ` — Print version information + + + +## `spin plugins show` + +Print information about a plugin + +**Usage:** `spin plugins USAGE: + show ` + +###### **Arguments:** + +* `` — Name of Spin plugin + +###### **Options:** + +* `--help ` — Print help information +* `--version ` — Print version information + + + +## `spin plugins uninstall` + +Remove a plugin from your installation + +**Usage:** `spin plugins USAGE: + uninstall ` + +###### **Arguments:** + +* `` — Name of Spin plugin + +###### **Options:** + +* `--help ` — Print help information +* `--version ` — Print version information + + + +## `spin plugins update` + +Fetch the latest Spin plugins from the spin-plugins repository + +**Usage:** `spin plugins USAGE: + update` + +###### **Options:** + +* `--help ` — Print help information +* `--version ` — Print version information + + + +## `spin plugins upgrade` + +Upgrade one or all plugins + +**Usage:** `spin plugins USAGE: + upgrade [OPTIONS] [PLUGIN_NAME]` + +###### **Arguments:** + +* `` — Name of Spin plugin to upgrade + +###### **Options:** + +* `-a`, `--all ` — Upgrade all plugins +* `--auth-header-value ` — Provide the value for the authorization header to be able to install a plugin from a private repository. (e.g) --auth-header-value "Bearer " +* `-d`, `--downgrade ` — Allow downgrading a plugin's version +* `-f`, `--file ` — Path to local plugin manifest +* `--help ` — Print help information +* `--override-compatibility-check ` — Overrides a failed compatibility check of the plugin with the current version of Spin +* `-u`, `--url ` — Path to remote plugin manifest +* `-v`, `--version ` — Specific version of a plugin to be install from the centralized plugins repository +* `--version ` — Print version information +* `-y`, `--yes ` — Skips prompt to accept the installation of the plugin[s] + + + +## `spin registry` + +Commands for working with OCI registries to distribute applications + +**Usage:** `spin USAGE: + registry ` + +###### **Subcommands:** + +* `login` — Log in to a registry +* `pull` — Pull a Spin application from a registry +* `push` — Push a Spin application to a registry + +###### **Options:** + +* `--help ` — Print help information +* `--version ` — Print version information + + + +## `spin registry login` + +Log in to a registry + +**Usage:** `spin registry USAGE: + login [OPTIONS] ` + +###### **Arguments:** + +* `` — OCI registry server (e.g. ghcr.io) + +###### **Options:** + +* `--help ` — Print help information +* `-p`, `--password ` — Password for the registry +* `--password-stdin ` — Take the password from stdin +* `-u`, `--username ` — Username for the registry +* `--version ` — Print version information + + + +## `spin registry pull` + +Pull a Spin application from a registry + +**Usage:** `spin registry USAGE: + pull [OPTIONS] ` + +###### **Arguments:** + +* `` — Reference in the registry of the published Spin application. This is a string whose format is defined by the registry standard, and generally consists of //:. E.g. ghcr.io/ogghead/spin-test-app:0.1.0 + +###### **Options:** + +* `--cache-dir ` — Cache directory for downloaded registry data +* `--help ` — Print help information +* `-k`, `--insecure ` — Ignore server certificate errors +* `--version ` — Print version information + + + +## `spin registry push` + +Push a Spin application to a registry + +**Usage:** `spin registry USAGE: + push [OPTIONS] ` + +###### **Arguments:** + +* `` — Reference in the registry of the Spin application. This is a string whose format is defined by the registry standard, and generally consists of //:. E.g. ghcr.io/ogghead/spin-test-app:0.1.0 + +###### **Options:** + +* `--annotation ` — Specifies the OCI image manifest annotations (in key=value format). Any existing value will be overwritten. Can be used multiple times +* `--build ` — Specifies to perform `spin build` before pushing the application +* `--cache-dir ` — Cache directory for downloaded registry data +* `--compose ` — Compose component dependencies before pushing the application. + + The default is to compose before pushing, which maximises compatibility with different Spin runtime hosts. Turning composition off can optimise bandwidth for shared dependencies, but makes the pushed image incompatible with hosts that cannot carry out composition themselves. + + Default value: `true` +* `-f`, `--from ` — The application to push. This may be a manifest (spin.toml) file, or a directory containing a spin.toml file. If omitted, it defaults to "spin.toml" +* `--help ` — Print help information +* `-k`, `--insecure ` — Ignore server certificate errors +* `--version ` — Print version information + + + +## `spin templates` + +Commands for working with WebAssembly component templates + +**Usage:** `spin USAGE: + templates ` + +###### **Subcommands:** + +* `install` — Install templates from a Git repository or local directory +* `list` — List the installed templates +* `uninstall` — Remove a template from your installation +* `upgrade` — Upgrade templates to match your current version of Spin + +###### **Options:** + +* `--help ` — Print help information +* `--version ` — Print version information + + + +## `spin templates install` + +Install templates from a Git repository or local directory. + +The files of the templates are copied to the local template store: a directory in your data or home directory. + +**Usage:** `spin templates USAGE: + install [OPTIONS]` + +###### **Options:** + +* `--branch ` — The optional branch of the git repository +* `--dir ` — Local directory containing the template(s) to install +* `--git ` — The URL of the templates git repository. The templates must be in a git repository in a "templates" directory +* `--help ` — Print help information +* `--tar ` — URL to a tarball in .tar.gz format containing the template(s) to install +* `--upgrade ` — If present, updates existing templates instead of skipping +* `--version ` — Print version information + + + +## `spin templates list` + +List the installed templates + +**Usage:** `spin templates USAGE: + list [OPTIONS]` + +###### **Options:** + +* `--help ` — Print help information +* `--tag ` — Filter templates matching all provided tags +* `--verbose ` — Whether to show additional template details in the list +* `--version ` — Print version information + + + +## `spin templates uninstall` + +Remove a template from your installation + +**Usage:** `spin templates USAGE: + uninstall ` + +###### **Arguments:** + +* `` — The template to uninstall + +###### **Options:** + +* `--help ` — Print help information +* `--version ` — Print version information + + + +## `spin templates upgrade` + +Upgrade templates to match your current version of Spin. + +The files of the templates are copied to the local template store: a directory in your data or home directory. + +**Usage:** `spin templates USAGE: + upgrade [OPTIONS]` + +###### **Options:** + +* `--all ` — By default, Spin displays the list of installed repositories and prompts you to choose which to upgrade. Pass this flag to upgrade all repositories without prompting +* `--branch ` — The optional branch of the git repository, if a specific repository is given +* `--help ` — Print help information +* `--repo ` — By default, Spin displays the list of installed repositories and prompts you to choose which to upgrade. Pass this flag to upgrade only the specified repository without prompting +* `--version ` — Print version information + + + +## `spin up` + +Start the Spin application + +**Usage:** `spin USAGE: + up [OPTIONS]` + +###### **Arguments:** + +* `` — All other args, to be passed through to the trigger + +###### **Options:** + +* `--build ` — For local apps, specifies to perform `spin build` before running the application. + + This is ignored on remote applications, as they are already built. +* `-c`, `--component-id ` — [Experimental] Component ID to run. This can be specified multiple times. The default is all components +* `--cache-dir ` — Cache directory for downloaded components and assets +* `--direct-mounts ` — For local apps with directory mounts and no excluded files, mount them directly instead of using a temporary directory. + + This allows you to update the assets on the host filesystem such that the updates are visible to the guest without a restart. This cannot be used with registry apps or apps which use file patterns and/or exclusions. +* `-e`, `--env ` — Pass an environment variable (key=value) to all components of the application +* `-f`, `--from ` — The application to run. This may be a manifest (spin.toml) file, a directory containing a spin.toml file, a remote registry reference, or a Wasm module (a .wasm file). If omitted, it defaults to "spin.toml" +* `-h`, `--help ` +* `--help ` — Print help information +* `-k`, `--insecure ` — Ignore server certificate errors from a registry +* `--temp ` — Temporary directory for the static assets of the components +* `--version ` — Print version information + + + +## `spin watch` + +Build and run the Spin application, rebuilding and restarting it when files change + +**Usage:** `spin USAGE: + watch [OPTIONS] [UP_ARGS]...` + +###### **Arguments:** + +* `` — Arguments to be passed through to spin up + +###### **Options:** + +* `-c`, `--clear ` — Clear the screen before each run +* `-d`, `--debounce ` — Set the timeout between detected change and re-execution, in milliseconds + + Default value: `100` +* `-f`, `--from ` — The application to watch. This may be a manifest (spin.toml) file, or a directory containing a spin.toml file. If omitted, it defaults to "spin.toml" +* `--help ` — Print help information +* `--skip-build ` — Only run the Spin application, restarting it when build artifacts change +* `--version ` — Print version information + + + +
+ + + This document was generated automatically by + clap-markdown. + +