Reference
Command line
The linkprofile commands and their options. You don't need any of them to publish with the starter: its workflow runs build for you. They need Node.js 22 or newer; npx downloads linkprofile the first time you run it.
npx linkprofile <command> [options]
| Command | What it does |
|---|---|
init |
Writes a starter profile.hjson and images/avatar.png. |
build |
Builds the page into a folder. |
preview |
Builds the page, serves it on your computer and rebuilds when files change. |
themes |
Lists the built-in themes. |
init
npx linkprofile init
Writes profile.hjson and images/avatar.png in the current folder: the same file and picture as the starter. If profile.hjson already exists, nothing is written and the command fails. An existing images/avatar.png is kept.
build
npx linkprofile build [--config <path>] [--out <dir>] [--url <url>]
| Option | Default | What it does |
|---|---|---|
--config <path> |
profile.hjson |
The profile to build. File paths in it are relative to its folder. |
--out <dir> |
dist |
The folder to write the page to. |
--url <url> |
None | The page's public address, used when the profile has no url. Must start with https:// or http://. |
The output folder holds:
index.html, your page;theme/, the theme's stylesheet and files;- the pictures your profile uses, at the same paths;
- everything in the
publicfolder next to your profile, copied as it is; .linkprofile, an empty marker file.
If a file from public has the same path as a file linkprofile writes, linkprofile's file replaces it, with a warning.
On success, build prints a summary such as Built dist/ with 5 links and 5 socials, using theme classic. Warnings go before it.
Output folder safety
build empties the output folder before writing to it, so it refuses folders that would lose your files. It stops with Refusing to use "<dir>" as the output directory if the folder:
- is the root of the disk;
- is, or contains, the current folder or the folder holding your profile;
- is inside
public; - would contain your profile or a picture it uses;
- exists and isn't a folder.
It stops with Refusing to empty "<dir>": it isn't a previous linkprofile build if the folder has files in it but no .linkprofile marker. Each build writes the marker, so building into the same folder again works. Delete the folder yourself, or choose another --out.
preview
npx linkprofile preview [--config <path>] [--port <number>]
| Option | Default | What it does |
|---|---|---|
--config <path> |
profile.hjson |
The profile to build. |
--port <number> |
4000 |
The port to serve on, from 0 to 65535. 0 picks a free one. |
Builds the page into a temporary folder, so dist is left alone, and serves it at the address it prints, such as Preview at http://127.0.0.1:4000. Only your computer can open it.
When any file in the profile's folder changes, the page rebuilds and the browser reloads. Changes in node_modules and .git are ignored. If a build fails, the browser shows the error instead of the page, and errors and warnings also appear in the terminal. Press Ctrl+C to stop.
If the port is taken, preview stops with Port 4000 is already in use; choose another with --port. Preview on your computer walks through it.
themes
npx linkprofile themes
Lists each built-in theme's name and a one-line description. Theme options lists their options.
Global options
| Option | What it does |
|---|---|
--help |
Prints the commands and options. |
--version |
Prints the linkprofile version. |
--debug |
On an error, also prints the stack trace. Useful when reporting a problem. |
Exit codes
| Code | Meaning |
|---|---|
0 |
Success. |
1 |
The command failed: an error in the profile, a missing file, an invalid --url, a refused output folder, a port in use, or init finding an existing profile.hjson. The message says which. |
2 |
The command line itself is wrong: no command, an unknown command or option, an option without its value, an extra argument, or an invalid --port. linkprofile prints the problem and the usage. |
Errors and warnings go to standard error; summaries go to standard output. Colours are used only when standard error is a terminal; set NO_COLOR to turn them off.
Something unclear? Open an issue or edit this page on GitHub.