# Retype CLI The Retype CLI is clean and simple. The majority of the time you will run just one command: `retype start` !!! Be sure to review the [project](/configuration/project.md) options available within the **retype.yml** as it does unlock more power, flexibility, and customization. !!! The `--help` option can be passed with any command to get additional details, for instance `retype start --help` will return all options for the `retype start` command. The command `retype --version` will return the current version number of your Retype install. See all public Retype [releases](https://github.com/retypeapp/retype/releases). Let's go through each of the `retype` CLI commands and be sure to check out the [Getting Started](/guides/getting-started.md) guide for step-by-step instructions on using each of these commands. ``` Description: Retype CLI Usage: retype [command] [options] Options: --info Display Retype information -v, --version Show version information -?, -h, --help Show help and usage information Commands: start Build and serve the project using a local development only web server init Initialize a new Retype project build Generate a static website from the project serve Serve the website in a local development only web server clean Clean the output directory stop Stop Retype web servers wallet Manage Your Retype Keys ``` --- ## `retype start` The `retype start` command is the easiest way to get your project built and running in a browser within seconds. ``` retype start ``` The `retype start` command will also watch for file changes and will automatically update the website in your web browser with the updated page. The `retype start` command automatically opens the default web browser on your machine and loads the website into the browser. You can suppress this automatic opening of the default web browser by passing the `--no-open` flag or its alias `-n`. ``` retype start -n ``` If you want Retype to wait briefly before reacting to file changes, pass the `--debounce ` option. This can be helpful when multiple file save events might happen in quick succession. ``` retype start --debounce 500 ``` ### Options ``` Description: Build and serve the project using a local development only web server Usage: retype start [] [options] Arguments: Path to the project root or project config file [Optional] Options: --debounce Rebuild delay in milliseconds --key Your Retype Key --host Custom Host name or IP address --password Private page password --port Custom TCP port --pro Enable Retype Pro preview -n, --no-open Prevent default web browser from being opened -v, --verbose Enable verbose logging -a, --api Watch for API changes -?, -h, --help Show help and usage information ``` !!!danger While it is technically possible to host your website publicly using `retype start` on your own web server hardware, **DON'T DO IT**. You should use a dedicated website hosting service, web server, or VPS service. Hosting options include, [GitHub Pages](/hosting/github-pages.md), [Netlify](/hosting/netlify.md), [Cloudflare](/hosting/cloudflare.md), or absolutely any other web hosting or VPS service. If you _really really really_ want to try public self-hosting using the built in web server, use [`retype serve`](#retype-serve). !!! --- ## `retype init` You can manually create a **retype.yml** file, or you can have Retype stub out a basic file with a few initial values by running the command `retype init`. From your command line, navigate to any folder location where you have one or more Markdown `.md` files, such as the root of a GitHub project, then run the following command: ``` retype init ``` Calling the `retype init` command will create a basic **retype.yml** file with the following default values: ```yml Sample retype.yml input: . output: .retype url: example.com # Add your website here branding: title: Project Name label: Docs links: - text: Getting Started link: https://retype.com/guides/getting-started/ footer: copyright: "© Copyright {{ year }}. All rights reserved." ``` All the configs are optional, but the above sample demonstrates a few of the options you will typically want to start with. See the [project](/configuration/project.md) configuration docs for a full list of all options. To change the title of the project, revise the `branding.title` config. For instance, let's change to `Company X`: ```yml branding: title: Company X ``` If there is already a **retype.yml** file within the project, running the `retype init` command will not create a new **retype.yml** file. The **retype.yml** file is not _actually_ required, but you will want to make custom [configurations](/configuration/project.md) to your project and this is how those instructions are passed to Retype. ### Options ``` Description: Initialize a new Retype project Usage: retype init [] [options] Arguments: Path to the project root [Optional] Options: --override JSON configuration overriding Retype config values -v, --verbose Enable verbose logging -?, -h, --help Show help and usage information ``` ///region override ### `--override` See the [`--override`](#retype---override) docs below for additional details. ///endregion --- ## `retype build` To generate your new website, run the command `retype build`. This command builds a new website based upon the `.md` files within the [`input`](/configuration/project.md) location. ``` retype build ``` Within just a few seconds, Retype will create a new website and save to the `output` location as defined in the **retype.yml**. By default, the `output` location is a new folder named `.retype`. You can rename to whatever you like, or adjust the path to generate the output to any other location, such as another sub-folder. If the `.md` documentation files for your project were not located in the root (`.`) but within a `docs` subfolder AND you wanted to have Retype send the output to a `website` folder, you would use the following config: ```yml input: docs output: website ``` Let's say you wanted your new Retype website to run from within a `docs` folder which was then also inside of a root `website` folder, then you would configure: ```yml input: docs output: website/docs ``` If you are hosting your website using [GitHub Pages](https://docs.github.com/en/github/working-with-github-pages/creating-a-github-pages-site) AND you wanted to host your website from the `docs` folder, you could then move your `.md` files into a different subfolder and configure as follows: ```yml input: src output: docs ``` The `input` and `output` configs provide unlimited flexibility to instruct Retype on where to get your project content and configurations files, and where to output the generated website. ### Options ``` Description: Generate a static website from the project Usage: retype build [] [options] Arguments: Path to the project root or project config file [Optional] Options: --output Custom path to the output directory --key Your Retype Key --password Private page password --override JSON configuration overriding project config values --strict [PRO] Return a non-zero exit code if the build had errors or warnings -w, --watch Watch for file changes -v, --verbose Enable verbose logging -a, --api Watch for API changes -?, -h, --help Show help and usage information ``` ### `--override` See the [`--override`](#retype---override) docs below for additional details. --- ## `retype serve` The `retype serve` command starts a local development only web server and hosts your website. ``` retype serve ``` The website generated by Retype is a static HTML and JavaScript site. No special server-side hosting, such as Node, PHP, or Ruby is required. A Retype generated website can be hosted on any web server or hosting service, such as [GitHub Pages](https://docs.github.com/en/github/working-with-github-pages/creating-a-github-pages-site), [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/), [Netlify](https://www.netlify.com/), or [Cloudflare Pages](https://pages.cloudflare.com/). You can also use any other local web server instead of `retype serve`. Retype only includes a web server out of convenience, not requirement. Any web server will do. A couple other simple web server options could be [live-server](https://www.npmjs.com/package/live-server) or [static-server](https://www.npmjs.com/package/static-server). ### Options ``` Description: Serve the website in a local development only web server Usage: retype serve [] [options] Arguments: Path to the project root or project config file [Optional] Options: --host Custom Host name or IP address --port Custom TCP port -l, --live Live reload open browsers when a change in the project output is detected -v, --verbose Enable verbose logging -?, -h, --help Show help and usage information ``` ### `--override` See the [`--override`](#retype---override) docs below for additional details. --- ## `retype clean` The `retype clean` command will delete the Retype managed files from the `output` folder. If you manually add files or another process adds files to the `output`, those files will not be removed by `retype clean`. Including the `--dry` flag triggers a dry run for the command and will list the files that _**would be**_ deleted if the `--dry` flag was not included. ### Options ``` Description: Clean the output directory Usage: retype clean [] [options] Arguments: Path to the project root or project config file [Optional] Options: --dry List files and directories that would be deleted -v, --verbose Enable verbose logging -?, -h, --help Show help and usage information ``` --- ## `retype stop` The `retype stop` command stops the Retype web server for the current project. ``` retype stop ``` If you have more than one Retype web server running, pass the `--list` option to review the available servers. ``` retype stop --list ``` Retype servers can be stopped by `--id`, `--index`, or `--port`. Use `retype stop --list` to discover the available `id` and `index` values, then pass the one you want to stop. ``` retype stop --port 5001 ``` Use the `--all` option to stop all running Retype web servers. ``` retype stop --all ``` ### Options ``` Description: Stop Retype web servers Usage: retype stop [] [options] Arguments: Path to the project root or project config file [Optional] Options: --list List running Retype web servers, including servers that may not be stoppable --all Stop all running Retype web servers --id Stop a specific Retype web server by id --index Stop a specific Retype web server by index --port Stop a specific Retype web server by port number -v, --verbose Enable verbose logging -?, -h, --help Show help and usage information ``` --- ## `retype wallet` The `retype wallet` command is for managing Retype keys. Retype keys are stored within an encrypted wallet file called **license.dat**. To add a Retype key to your wallet, run the following command: ``` retype wallet --add ``` Once a key is added to your wallet, the key does not need to be added again. The key is stored in the wallet and Retype will read the key from the wallet with future builds. A Retype key can also be passed during a build. The key is NOT stored in wallet. The key would need to be passed with each call to `retype build`. ``` retype build --key ``` ### RETYPE_KEY See how to configure a [`RETYPE_KEY`](../configuration/envvars.md/#retype_key) Environment variable for an option to set your project key during runtime. ### Options ``` Description: Manage Your Retype Keys Usage: retype wallet [options] Options: --add Add a key to the wallet --remove Remove a key from the wallet --list List the stored keys --clear Clear the wallet -?, -h, --help Show help and usage information ``` --- ## `retype --override` The Retype CLI [`build`](#retype-build) command supports the `--override` option to allow dynamically modifying **retype.yml** project configurations during build. The `--override` option is helpful in certain scenarios such as generating websites requiring different `url` configs, without the need to maintain several **retype.yml** files. The CLI expects an escaped json object to be passed as the option value. Retype merges the **retype.yml** configuration with the provided json object in a way that colliding configurations from the json override will overwrite the **retype.yml** values. !!! The `--override` json object may contain duplicate keys which will be processed sequentially. Last in wins. !!! ### Basic config Using the following **retype.yml** project configuration file as an example: ~~~yml **retype.yml** url: https://retype.com ~~~ The command below will build the website with the url `https://beta.retype.com`. ``` retype build --override "{ \"url\": \"https://beta.retype.com\" }" ``` ### Nested config The following sample demonstrates overriding a more complex configuration object. Using the following **retype.yml** project configuration file as an example, let's change the [`label`](/configuration/project.md#branding-label) to `beta`, instead of `v1.10`. ~~~yml **retype.yml** branding: title: Retype label: v1.10 ~~~ The `retype build --override` would be: ``` retype build --override "{ \"branding\": { \"label\": \"beta\"} }" ``` To completely remove all the configs in `branding`, pass `null`: ``` retype build --override "{ \"branding\": null }" ``` ### Add to list The following command will add a `GitHub` link to the list of [`links`](/configuration/project.md#links). ~~~yml **retype.yml** links: - link: Retype text: https://retype.com ~~~ ``` retype build --override "{ \"links\": [{ \"link\": \"https://github.com/retypeapp/retype\", \"text\": \"GitHub\" }] }" ``` ### Remove config Passing `null` will remove the corresponding configuration value. In the following sample, the website will be built as though `url` was not configured. ``` retype build --override "{ \"url\": null }" ```