forked from auxolotl/docs
2989 lines
93 KiB
HTML
2989 lines
93 KiB
HTML
|
||
<!doctype html>
|
||
<html lang="en" class="no-js">
|
||
<head>
|
||
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||
|
||
<meta name="description" content="Aux Documentation">
|
||
|
||
|
||
<meta name="author" content="Nixpkgs Aux, and Lix Contributors">
|
||
|
||
|
||
<link rel="canonical" href="https://docs.auxolotl.org/Lix/contributing/cli-guideline/">
|
||
|
||
|
||
<link rel="prev" href="../">
|
||
|
||
|
||
<link rel="next" href="../cxx/">
|
||
|
||
|
||
<link rel="icon" href="../../../assets/aux-logo.svg">
|
||
<meta name="generator" content="mkdocs-1.6.0, mkdocs-material-9.5.29">
|
||
|
||
|
||
|
||
<title>CLI guideline - Aux Docs</title>
|
||
|
||
|
||
|
||
<link rel="stylesheet" href="../../../assets/stylesheets/main.76a95c52.min.css">
|
||
|
||
|
||
<link rel="stylesheet" href="../../../assets/stylesheets/palette.06af60db.min.css">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||
<link rel="stylesheet" href="https://fonts.bunny.net/css?family=IBM+Plex+Sans:300,300i,400,400i,700,700i%7CIBM+Plex+Mono:400,400i,700,700i&display=fallback">
|
||
<style>:root{--md-text-font:"IBM Plex Sans";--md-code-font:"IBM Plex Mono"}</style>
|
||
|
||
|
||
|
||
<script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce((e,_)=>(e<<5)-e+_.charCodeAt(0),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<meta property="og:type" content="website" >
|
||
|
||
<meta property="og:title" content="CLI guideline - Aux Docs" >
|
||
|
||
<meta property="og:description" content="Aux Documentation" >
|
||
|
||
<meta property="og:image" content="https://docs.auxolotl.org/assets/images/social/Lix/contributing/cli-guideline.png" >
|
||
|
||
<meta property="og:image:type" content="image/png" >
|
||
|
||
<meta property="og:image:width" content="1200" >
|
||
|
||
<meta property="og:image:height" content="630" >
|
||
|
||
<meta property="og:url" content="https://docs.auxolotl.org/Lix/contributing/cli-guideline/" >
|
||
|
||
<meta name="twitter:card" content="summary_large_image" >
|
||
|
||
<meta name="twitter:title" content="CLI guideline - Aux Docs" >
|
||
|
||
<meta name="twitter:description" content="Aux Documentation" >
|
||
|
||
<meta name="twitter:image" content="https://docs.auxolotl.org/assets/images/social/Lix/contributing/cli-guideline.png" >
|
||
|
||
|
||
|
||
</head>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<body dir="ltr" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="blue">
|
||
|
||
|
||
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
|
||
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
|
||
<label class="md-overlay" for="__drawer"></label>
|
||
<div data-md-component="skip">
|
||
|
||
|
||
<a href="#cli-guideline" class="md-skip">
|
||
Skip to content
|
||
</a>
|
||
|
||
</div>
|
||
<div data-md-component="announce">
|
||
|
||
</div>
|
||
|
||
|
||
|
||
|
||
<header class="md-header" data-md-component="header">
|
||
<nav class="md-header__inner md-grid" aria-label="Header">
|
||
<a href="../../.." title="Aux Docs" class="md-header__button md-logo" aria-label="Aux Docs" data-md-component="logo">
|
||
|
||
<img src="../../../assets/aux-logo.svg" alt="logo">
|
||
|
||
</a>
|
||
<label class="md-header__button md-icon" for="__drawer">
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"/></svg>
|
||
</label>
|
||
<div class="md-header__title" data-md-component="header-title">
|
||
<div class="md-header__ellipsis">
|
||
<div class="md-header__topic">
|
||
<span class="md-ellipsis">
|
||
Aux Docs
|
||
</span>
|
||
</div>
|
||
<div class="md-header__topic" data-md-component="header-topic">
|
||
<span class="md-ellipsis">
|
||
|
||
CLI guideline
|
||
|
||
</span>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<form class="md-header__option" data-md-component="palette">
|
||
|
||
|
||
|
||
|
||
<input class="md-option" data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="blue" aria-label="Dark Mode" type="radio" name="__palette" id="__palette_0">
|
||
|
||
<label class="md-header__button md-icon" title="Dark Mode" for="__palette_1" hidden>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m17.75 4.09-2.53 1.94.91 3.06-2.63-1.81-2.63 1.81.91-3.06-2.53-1.94L12.44 4l1.06-3 1.06 3 3.19.09m3.5 6.91-1.64 1.25.59 1.98-1.7-1.17-1.7 1.17.59-1.98L15.75 11l2.06-.05L18.5 9l.69 1.95 2.06.05m-2.28 4.95c.83-.08 1.72 1.1 1.19 1.85-.32.45-.66.87-1.08 1.27C15.17 23 8.84 23 4.94 19.07c-3.91-3.9-3.91-10.24 0-14.14.4-.4.82-.76 1.27-1.08.75-.53 1.93.36 1.85 1.19-.27 2.86.69 5.83 2.89 8.02a9.96 9.96 0 0 0 8.02 2.89m-1.64 2.02a12.08 12.08 0 0 1-7.8-3.47c-2.17-2.19-3.33-5-3.49-7.82-2.81 3.14-2.7 7.96.31 10.98 3.02 3.01 7.84 3.12 10.98.31Z"/></svg>
|
||
</label>
|
||
|
||
|
||
|
||
|
||
|
||
<input class="md-option" data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme="slate" data-md-color-primary="indigo" data-md-color-accent="blue" aria-label="Light Mode" type="radio" name="__palette" id="__palette_1">
|
||
|
||
<label class="md-header__button md-icon" title="Light Mode" for="__palette_0" hidden>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 7a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5m0 2a3 3 0 0 0-3 3 3 3 0 0 0 3 3 3 3 0 0 0 3-3 3 3 0 0 0-3-3m0-7 2.39 3.42C13.65 5.15 12.84 5 12 5c-.84 0-1.65.15-2.39.42L12 2M3.34 7l4.16-.35A7.2 7.2 0 0 0 5.94 8.5c-.44.74-.69 1.5-.83 2.29L3.34 7m.02 10 1.76-3.77a7.131 7.131 0 0 0 2.38 4.14L3.36 17M20.65 7l-1.77 3.79a7.023 7.023 0 0 0-2.38-4.15l4.15.36m-.01 10-4.14.36c.59-.51 1.12-1.14 1.54-1.86.42-.73.69-1.5.83-2.29L20.64 17M12 22l-2.41-3.44c.74.27 1.55.44 2.41.44.82 0 1.63-.17 2.37-.44L12 22Z"/></svg>
|
||
</label>
|
||
|
||
|
||
</form>
|
||
|
||
|
||
|
||
<script>var media,input,key,value,palette=__md_get("__palette");if(palette&&palette.color){"(prefers-color-scheme)"===palette.color.media&&(media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']"),palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent"));for([key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
|
||
|
||
|
||
|
||
<label class="md-header__button md-icon" for="__search">
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg>
|
||
</label>
|
||
<div class="md-search" data-md-component="search" role="dialog">
|
||
<label class="md-search__overlay" for="__search"></label>
|
||
<div class="md-search__inner" role="search">
|
||
<form class="md-search__form" name="search">
|
||
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
|
||
<label class="md-search__icon md-icon" for="__search">
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg>
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg>
|
||
</label>
|
||
<nav class="md-search__options" aria-label="Search">
|
||
|
||
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41Z"/></svg>
|
||
</button>
|
||
</nav>
|
||
|
||
</form>
|
||
<div class="md-search__output">
|
||
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
|
||
<div class="md-search-result" data-md-component="search-result">
|
||
<div class="md-search-result__meta">
|
||
Initializing search
|
||
</div>
|
||
<ol class="md-search-result__list" role="presentation"></ol>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<div class="md-header__source">
|
||
<a href="https://git.auxolotl.org/auxolotl/docs" title="Go to repository" class="md-source" data-md-component="source">
|
||
<div class="md-source__icon md-icon">
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M16.777 0a2.9 2.9 0 1 1-2.529 4.322H12.91a4.266 4.266 0 0 0-4.265 4.195v2.118a7.076 7.076 0 0 1 4.147-1.42l.118-.002h1.338a2.9 2.9 0 0 1 5.43 1.422 2.9 2.9 0 0 1-5.43 1.422H12.91a4.266 4.266 0 0 0-4.265 4.195v2.319A2.9 2.9 0 0 1 7.222 24 2.9 2.9 0 0 1 5.8 18.57V8.589a7.109 7.109 0 0 1 6.991-7.108l.118-.001h1.338A2.9 2.9 0 0 1 16.778 0ZM7.223 19.905a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Zm9.554-10.464a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.39Zm0-7.735a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Z"/></svg>
|
||
</div>
|
||
<div class="md-source__repository">
|
||
auxolotl/docs
|
||
</div>
|
||
</a>
|
||
</div>
|
||
|
||
</nav>
|
||
|
||
</header>
|
||
|
||
<div class="md-container" data-md-component="container">
|
||
|
||
|
||
|
||
|
||
|
||
<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
|
||
<div class="md-grid">
|
||
<ul class="md-tabs__list">
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item">
|
||
<a href="../../.." class="md-tabs__link">
|
||
|
||
|
||
|
||
|
||
Aux Documentation Hub
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item">
|
||
<a href="../../../TODO/" class="md-tabs__link">
|
||
|
||
|
||
|
||
|
||
TODO
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item">
|
||
<a href="../../../Aux/" class="md-tabs__link">
|
||
|
||
|
||
|
||
|
||
Aux
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item md-tabs__item--active">
|
||
<a href="../../" class="md-tabs__link">
|
||
|
||
|
||
|
||
|
||
Lix
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item">
|
||
<a href="../../../NixOS/appstream/" class="md-tabs__link">
|
||
|
||
|
||
|
||
|
||
NixOS
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-tabs__item">
|
||
<a href="../../../Nixpkgs/" class="md-tabs__link">
|
||
|
||
|
||
|
||
|
||
Nixpkgs
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
|
||
|
||
|
||
<main class="md-main" data-md-component="main">
|
||
<div class="md-main__inner md-grid">
|
||
|
||
|
||
|
||
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
|
||
<div class="md-sidebar__scrollwrap">
|
||
<div class="md-sidebar__inner">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<nav class="md-nav md-nav--primary md-nav--lifted" aria-label="Navigation" data-md-level="0">
|
||
<label class="md-nav__title" for="__drawer">
|
||
<a href="../../.." title="Aux Docs" class="md-nav__button md-logo" aria-label="Aux Docs" data-md-component="logo">
|
||
|
||
<img src="../../../assets/aux-logo.svg" alt="logo">
|
||
|
||
</a>
|
||
Aux Docs
|
||
</label>
|
||
|
||
<div class="md-nav__source">
|
||
<a href="https://git.auxolotl.org/auxolotl/docs" title="Go to repository" class="md-source" data-md-component="source">
|
||
<div class="md-source__icon md-icon">
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M16.777 0a2.9 2.9 0 1 1-2.529 4.322H12.91a4.266 4.266 0 0 0-4.265 4.195v2.118a7.076 7.076 0 0 1 4.147-1.42l.118-.002h1.338a2.9 2.9 0 0 1 5.43 1.422 2.9 2.9 0 0 1-5.43 1.422H12.91a4.266 4.266 0 0 0-4.265 4.195v2.319A2.9 2.9 0 0 1 7.222 24 2.9 2.9 0 0 1 5.8 18.57V8.589a7.109 7.109 0 0 1 6.991-7.108l.118-.001h1.338A2.9 2.9 0 0 1 16.778 0ZM7.223 19.905a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Zm9.554-10.464a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.39Zm0-7.735a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Z"/></svg>
|
||
</div>
|
||
<div class="md-source__repository">
|
||
auxolotl/docs
|
||
</div>
|
||
</a>
|
||
</div>
|
||
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../../.." class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Aux Documentation Hub
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../../../TODO/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
TODO
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
<a href="../../../Aux/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Aux
|
||
</span>
|
||
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
|
||
</a>
|
||
|
||
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
|
||
|
||
|
||
|
||
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" checked>
|
||
|
||
|
||
|
||
<div class="md-nav__link md-nav__container">
|
||
<a href="../../" class="md-nav__link ">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Lix
|
||
</span>
|
||
|
||
|
||
</a>
|
||
|
||
|
||
<label class="md-nav__link " for="__nav_4" id="__nav_4_label" tabindex="">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
</label>
|
||
|
||
</div>
|
||
|
||
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="true">
|
||
<label class="md-nav__title" for="__nav_4">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
Lix
|
||
</label>
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../../glossary/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Glossary
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../../quick-start/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Quick Start
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
<a href="../../Advanced-Topics/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Advanced Topics
|
||
</span>
|
||
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
|
||
</a>
|
||
|
||
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
<a href="../../Command-Reference/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Command Reference
|
||
</span>
|
||
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
|
||
</a>
|
||
|
||
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
<a href="../../Package-Management/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Package Management
|
||
</span>
|
||
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
|
||
</a>
|
||
|
||
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
<a href="../../architecture/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Architecture
|
||
</span>
|
||
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
|
||
</a>
|
||
|
||
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
|
||
|
||
|
||
|
||
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4_8" checked>
|
||
|
||
|
||
|
||
<div class="md-nav__link md-nav__container">
|
||
<a href="../" class="md-nav__link ">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Contributing
|
||
</span>
|
||
|
||
|
||
</a>
|
||
|
||
|
||
<label class="md-nav__link " for="__nav_4_8" id="__nav_4_8_label" tabindex="0">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
</label>
|
||
|
||
</div>
|
||
|
||
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_4_8_label" aria-expanded="true">
|
||
<label class="md-nav__title" for="__nav_4_8">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
Contributing
|
||
</label>
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--active">
|
||
|
||
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
|
||
|
||
|
||
|
||
|
||
|
||
<label class="md-nav__link md-nav__link--active" for="__toc">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
CLI guideline
|
||
</span>
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
</label>
|
||
|
||
<a href="./" class="md-nav__link md-nav__link--active">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
CLI guideline
|
||
</span>
|
||
|
||
|
||
</a>
|
||
|
||
|
||
|
||
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<label class="md-nav__title" for="__toc">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
Table of contents
|
||
</label>
|
||
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#goals" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Goals
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#overview" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Overview
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#naming-the-commands" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Naming the COMMANDS
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Naming the COMMANDS">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#naming-rules" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Naming rules
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#classification" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Classification
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#help-is-essential" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Help is essential
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Help is essential">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#looking-for-help" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Looking for help
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#anticipate-where-help-is-needed" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Anticipate where help is needed
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Anticipate where help is needed">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#shell-completion" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Shell completion
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#wrong-input" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Wrong input
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#next-steps" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Next steps
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#educate-the-user" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Educate the user
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#input" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Input
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Input">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#naming-the-options" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Naming the OPTIONS
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#prompt-when-input-not-provided" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Prompt when input not provided
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#output" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Output
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Output">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#follow-best-practices" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Follow best practices
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#errors-wip" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Errors (WIP)
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#not-only-for-humans" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Not only for humans
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#returning-future-proof-json" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Returning future proof JSON
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Returning future proof JSON">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#examples" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Examples
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#dialog-with-the-user" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Dialog with the user
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#text-alignment" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Text alignment
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#dim-bright" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Dim / Bright
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#colors" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Colors
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#special-unicode-characters" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Special (Unicode) characters
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#emojis" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Emojis
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#tables" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Tables
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#interactive-output" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Interactive output
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Interactive output">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#progress" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Progress
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#search" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Search
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#prompt" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Prompt
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#verbosity" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Verbosity
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#appendix-1-commands-naming-exceptions" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Appendix 1: Commands naming exceptions
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../cxx/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
C++ style guide
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../experimental-features/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
What are experimental features?
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../hacking/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Hacking
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="../testing/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Running tests
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
<a href="../../installation/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Installation
|
||
</span>
|
||
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
|
||
</a>
|
||
|
||
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
<a href="../../language/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Language
|
||
</span>
|
||
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
|
||
</a>
|
||
|
||
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
<a href="../../protocols/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Protocols
|
||
</span>
|
||
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
|
||
</a>
|
||
|
||
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
<a href="../../release-notes/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Release notes
|
||
</span>
|
||
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
|
||
</a>
|
||
|
||
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
<a href="../../../NixOS/appstream/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
NixOS
|
||
</span>
|
||
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
|
||
</a>
|
||
|
||
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
<a href="../../../Nixpkgs/" class="md-nav__link">
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Nixpkgs
|
||
</span>
|
||
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
|
||
</a>
|
||
|
||
|
||
|
||
</li>
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
|
||
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
|
||
<div class="md-sidebar__scrollwrap">
|
||
<div class="md-sidebar__inner">
|
||
|
||
|
||
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<label class="md-nav__title" for="__toc">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
Table of contents
|
||
</label>
|
||
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#goals" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Goals
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#overview" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Overview
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#naming-the-commands" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Naming the COMMANDS
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Naming the COMMANDS">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#naming-rules" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Naming rules
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#classification" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Classification
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#help-is-essential" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Help is essential
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Help is essential">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#looking-for-help" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Looking for help
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#anticipate-where-help-is-needed" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Anticipate where help is needed
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Anticipate where help is needed">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#shell-completion" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Shell completion
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#wrong-input" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Wrong input
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#next-steps" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Next steps
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#educate-the-user" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Educate the user
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#input" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Input
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Input">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#naming-the-options" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Naming the OPTIONS
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#prompt-when-input-not-provided" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Prompt when input not provided
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#output" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Output
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Output">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#follow-best-practices" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Follow best practices
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#errors-wip" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Errors (WIP)
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#not-only-for-humans" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Not only for humans
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#returning-future-proof-json" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Returning future proof JSON
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Returning future proof JSON">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#examples" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Examples
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#dialog-with-the-user" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Dialog with the user
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#text-alignment" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Text alignment
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#dim-bright" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Dim / Bright
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#colors" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Colors
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#special-unicode-characters" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Special (Unicode) characters
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#emojis" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Emojis
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#tables" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Tables
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#interactive-output" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Interactive output
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Interactive output">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#progress" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Progress
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#search" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Search
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#prompt" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Prompt
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#verbosity" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Verbosity
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#appendix-1-commands-naming-exceptions" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Appendix 1: Commands naming exceptions
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
|
||
<div class="md-content" data-md-component="content">
|
||
<article class="md-content__inner md-typeset">
|
||
|
||
|
||
|
||
|
||
<h1 id="cli-guideline">CLI guideline</h1>
|
||
<h3 id="goals">Goals</h3>
|
||
<p>Purpose of this document is to provide a clear direction to <strong>help design
|
||
delightful command line</strong> experience. This document contains guidelines to
|
||
follow to ensure a consistent and approachable user experience.</p>
|
||
<h3 id="overview">Overview</h3>
|
||
<p><code>nix</code> command provides a single entry to a number of sub-commands that help
|
||
<strong>developers and system administrators</strong> in the life-cycle of a software
|
||
project. We particularly need to pay special attention to help and assist new
|
||
users of Lix.</p>
|
||
<h2 id="naming-the-commands">Naming the <code>COMMANDS</code></h2>
|
||
<p>Words matter. Naming is an important part of the usability. Users will be
|
||
interacting with Lix on a regular basis so we should <strong>name things for ease of
|
||
understanding</strong>.</p>
|
||
<p>We recommend following the <a href="https://en.wikipedia.org/wiki/Principle_of_least_astonishment">Principle of Least
|
||
Astonishment</a>.
|
||
This means that you should <strong>never use acronyms or abbreviations</strong> unless they
|
||
are commonly used in other tools (e.g. <code>nix init</code>). And if the command name is
|
||
too long (> 10-12 characters) then shortening it makes sense (e.g.
|
||
“prioritization” → “priority”).</p>
|
||
<p>Commands should <strong>follow a noun-verb dialogue</strong>. Although noun-verb formatting
|
||
seems backwards from a speaking perspective (i.e. <code>nix store copy</code> vs. <code>nix
|
||
copy store</code>) it allows us to organize commands the same way users think about
|
||
completing an action (the group first, then the command).</p>
|
||
<h3 id="naming-rules">Naming rules</h3>
|
||
<p>Rules are there to guide you by limiting your options. But not everything can
|
||
fit the rules all the time. In those cases document the exceptions in <a href="#appendix-1-commands-naming-exceptions">Appendix
|
||
1: Commands naming exceptions</a> and
|
||
provide reason. The rules want to force a Nix developer to look, not just at
|
||
the command at hand, but also the command in a full context alongside other
|
||
<code>nix</code> commands.</p>
|
||
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>nix<span class="w"> </span><span class="o">[</span><GROUP><span class="o">]</span><span class="w"> </span><COMMAND><span class="w"> </span><span class="o">[</span><ARGUMENTS><span class="o">]</span><span class="w"> </span><span class="o">[</span><OPTIONS><span class="o">]</span>
|
||
</code></pre></div>
|
||
<ul>
|
||
<li><code>GROUP</code>, <code>COMMAND</code>, <code>ARGUMENTS</code> and <code>OPTIONS</code> should be lowercase and in a
|
||
singular form.</li>
|
||
<li><code>GROUP</code> should be a <strong>NOUN</strong>.</li>
|
||
<li><code>COMMAND</code> should be a <strong>VERB</strong>.</li>
|
||
<li><code>ARGUMENTS</code> and <code>OPTIONS</code> are discussed in <a href="#input"><em>Input</em> section</a>.</li>
|
||
</ul>
|
||
<h3 id="classification">Classification</h3>
|
||
<p>Some commands are more important, some less. While we want all of our commands
|
||
to be perfect we can only spend limited amount of time testing and improving
|
||
them.</p>
|
||
<p>This classification tries to separate commands in 3 categories in terms of
|
||
their importance in regards to the new users. Users who are likely to be
|
||
impacted the most by bad user experience.</p>
|
||
<ul>
|
||
<li><strong>Main commands</strong></li>
|
||
</ul>
|
||
<p>Commands used for our main use cases and most likely used by new users. We
|
||
expect attention to details, such as:</p>
|
||
<div class="highlight"><pre><span></span><code>- Proper use of [colors](#colors), [emojis](#special-unicode-characters)
|
||
and [aligning of text](#text-alignment).
|
||
- [Autocomplete](#shell-completion) of options.
|
||
- Show [next possible steps](#next-steps).
|
||
- Showing some [“tips”](#educate-the-user) when running logs running tasks
|
||
(eg. building / downloading) in order to teach users interesting bits of
|
||
Nix ecosystem.
|
||
- [Help pages](#help-is-essential) to be as good as we can write them
|
||
pointing to external documentation and tutorials for more.
|
||
</code></pre></div>
|
||
<p>Examples of such commands: <code>nix init</code>, <code>nix develop</code>, <code>nix build</code>, <code>nix run</code>,
|
||
...</p>
|
||
<ul>
|
||
<li><strong>Infrequently used commands</strong></li>
|
||
</ul>
|
||
<p>From infrequently used commands we expect less attention to details, but
|
||
still some:</p>
|
||
<div class="highlight"><pre><span></span><code>- Proper use of [colors](#colors), [emojis](#special-unicode-characters)
|
||
and [aligning of text](#text-alignment).
|
||
- [Autocomplete](#shell-completion) of options.
|
||
</code></pre></div>
|
||
<p>Examples of such commands: <code>nix doctor</code>, <code>nix edit</code>, <code>nix eval</code>, ...</p>
|
||
<ul>
|
||
<li><strong>Utility and scripting commands</strong></li>
|
||
</ul>
|
||
<p>Commands that expose certain internal functionality of <code>nix</code>, mostly used by
|
||
other scripts.</p>
|
||
<div class="highlight"><pre><span></span><code>- [Autocomplete](#shell-completion) of options.
|
||
</code></pre></div>
|
||
<p>Examples of such commands: <code>nix store copy</code>, <code>nix hash base16</code>, <code>nix store
|
||
ping</code>, ...</p>
|
||
<h2 id="help-is-essential">Help is essential</h2>
|
||
<p>Help should be built into your command line so that new users can gradually
|
||
discover new features when they need them.</p>
|
||
<h3 id="looking-for-help">Looking for help</h3>
|
||
<p>Since there is no standard way how user will look for help we rely on ways help
|
||
is provided by commonly used tools. As a guide for this we took <code>git</code> and
|
||
whenever in doubt look at it as a preferred direction.</p>
|
||
<p>The rules are:</p>
|
||
<ul>
|
||
<li>Help is shown by using <code>--help</code> or <code>help</code> command (eg <code>nix</code> <code>--``help</code> or
|
||
<code>nix help</code>).</li>
|
||
<li>For non-COMMANDs (eg. <code>nix</code> <code>--``help</code> and <code>nix store</code> <code>--``help</code>) we <strong>show
|
||
a summary</strong> of most common use cases. Summary is presented on the STDOUT
|
||
without any use of PAGER.</li>
|
||
<li>For COMMANDs (eg. <code>nix init</code> <code>--``help</code> or <code>nix help init</code>) we display the
|
||
man page of that command. By default the PAGER is used (as in <code>git</code>).</li>
|
||
<li>At the end of either summary or man page there should be an URL pointing to
|
||
an online version of more detailed documentation.</li>
|
||
<li>The structure of summaries and man pages should be the same as in <code>git</code>.</li>
|
||
</ul>
|
||
<h3 id="anticipate-where-help-is-needed">Anticipate where help is needed</h3>
|
||
<p>Even better then requiring the user to search for help is to anticipate and
|
||
predict when user might need it. Either because the lack of discoverability,
|
||
typo in the input or simply taking the opportunity to teach the user of
|
||
interesting - but less visible - details.</p>
|
||
<h4 id="shell-completion">Shell completion</h4>
|
||
<p>This type of help is most common and almost expected by users. We need to
|
||
<strong>provide the best shell completion</strong> for <code>bash</code>, <code>zsh</code> and <code>fish</code>.</p>
|
||
<p>Completion needs to be <strong>context aware</strong>, this mean when a user types:</p>
|
||
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>nix<span class="w"> </span>build<span class="w"> </span>n<TAB>
|
||
</code></pre></div>
|
||
<p>we need to display a list of flakes starting with <code>n</code>.</p>
|
||
<h4 id="wrong-input">Wrong input</h4>
|
||
<p>As we all know we humans make mistakes, all the time. When a typo - intentional
|
||
or unintentional - is made, we should prompt for closest possible options or
|
||
point to the documentation which would educate user to not make the same
|
||
errors. Here are few examples:</p>
|
||
<p>In first example we prompt the user for typing wrong command name:</p>
|
||
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>nix<span class="w"> </span>int
|
||
------------------------------------------------------------------------
|
||
<span class="w"> </span>Error!<span class="w"> </span>Command<span class="w"> </span><span class="sb">`</span>int<span class="sb">`</span><span class="w"> </span>not<span class="w"> </span>found.
|
||
------------------------------------------------------------------------
|
||
<span class="w"> </span>Did<span class="w"> </span>you<span class="w"> </span>mean:
|
||
<span class="w"> </span><span class="p">|</span>><span class="w"> </span>nix<span class="w"> </span>init
|
||
<span class="w"> </span><span class="p">|</span>><span class="w"> </span>nix<span class="w"> </span>input
|
||
</code></pre></div>
|
||
<p>Sometimes users will make mistake either because of a typo or simply because of
|
||
lack of discoverability. Our handling of this cases needs to be context
|
||
sensitive.</p>
|
||
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>nix<span class="w"> </span>init<span class="w"> </span>--template<span class="o">=</span>template#pyton
|
||
------------------------------------------------------------------------
|
||
<span class="w"> </span>Error!<span class="w"> </span>Template<span class="w"> </span><span class="sb">`</span>template#pyton<span class="sb">`</span><span class="w"> </span>not<span class="w"> </span>found.
|
||
------------------------------------------------------------------------
|
||
Initializing<span class="w"> </span>Nix<span class="w"> </span>project<span class="w"> </span>at<span class="w"> </span><span class="sb">`</span>/path/to/here<span class="sb">`</span>.
|
||
<span class="w"> </span>Select<span class="w"> </span>a<span class="w"> </span>template<span class="w"> </span><span class="k">for</span><span class="w"> </span>you<span class="w"> </span>new<span class="w"> </span>project:
|
||
<span class="w"> </span><span class="p">|</span>><span class="w"> </span>template#python
|
||
<span class="w"> </span>template#python-pip
|
||
<span class="w"> </span>template#python-poetry
|
||
</code></pre></div>
|
||
<h4 id="next-steps">Next steps</h4>
|
||
<p>It can be invaluable to newcomers to show what a possible next steps and what
|
||
is the usual development workflow with Lix. For example:</p>
|
||
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>nix<span class="w"> </span>init<span class="w"> </span>--template<span class="o">=</span>template#python
|
||
Initializing<span class="w"> </span>project<span class="w"> </span><span class="sb">`</span>template#python<span class="sb">`</span>
|
||
<span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="sb">`</span>/home/USER/dev/new-project<span class="sb">`</span>
|
||
|
||
<span class="w"> </span>Next<span class="w"> </span>steps
|
||
<span class="w"> </span><span class="p">|</span>><span class="w"> </span>nix<span class="w"> </span>develop<span class="w"> </span>--<span class="w"> </span>to<span class="w"> </span>enter<span class="w"> </span>development<span class="w"> </span>environment
|
||
<span class="w"> </span><span class="p">|</span>><span class="w"> </span>nix<span class="w"> </span>build<span class="w"> </span>--<span class="w"> </span>to<span class="w"> </span>build<span class="w"> </span>your<span class="w"> </span>project
|
||
</code></pre></div>
|
||
<h4 id="educate-the-user">Educate the user</h4>
|
||
<p>We should take any opportunity to <strong>educate users</strong>, but at the same time we
|
||
must <strong>be very very careful to not annoy users</strong>. There is a thin line between
|
||
being helpful and being annoying.</p>
|
||
<p>An example of educating users might be to provide <em>Tips</em> in places where they
|
||
are waiting.</p>
|
||
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>nix<span class="w"> </span>build
|
||
<span class="w"> </span>Started<span class="w"> </span>building<span class="w"> </span>my-project<span class="w"> </span><span class="m">1</span>.2.3
|
||
<span class="w"> </span>Downloaded<span class="w"> </span>python3.8-poetry<span class="w"> </span><span class="m">1</span>.2.3<span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="m">5</span>.3<span class="w"> </span>seconds
|
||
<span class="w"> </span>Downloaded<span class="w"> </span>python3.8-requests<span class="w"> </span><span class="m">1</span>.2.3<span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="m">5</span>.3<span class="w"> </span>seconds
|
||
------------------------------------------------------------------------
|
||
<span class="w"> </span>Press<span class="w"> </span><span class="sb">`</span>v<span class="sb">`</span><span class="w"> </span>to<span class="w"> </span>increase<span class="w"> </span>logs<span class="w"> </span>verbosity
|
||
<span class="w"> </span><span class="p">|</span>><span class="w"> </span><span class="sb">`</span>?<span class="sb">`</span><span class="w"> </span>to<span class="w"> </span>see<span class="w"> </span>other<span class="w"> </span>options
|
||
------------------------------------------------------------------------
|
||
<span class="w"> </span>Learn<span class="w"> </span>something<span class="w"> </span>new<span class="w"> </span>with<span class="w"> </span>every<span class="w"> </span>build...
|
||
<span class="w"> </span><span class="p">|</span>><span class="w"> </span>See<span class="w"> </span>last<span class="w"> </span>logs<span class="w"> </span>of<span class="w"> </span>a<span class="w"> </span>build<span class="w"> </span>with<span class="w"> </span><span class="sb">`</span>nix<span class="w"> </span>log<span class="w"> </span>--last<span class="sb">`</span><span class="w"> </span>command.
|
||
------------------------------------------------------------------------
|
||
<span class="w"> </span>Evaluated<span class="w"> </span>my-project<span class="w"> </span><span class="m">1</span>.2.3<span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="m">14</span>.43<span class="w"> </span>seconds
|
||
Downloading<span class="w"> </span><span class="o">[</span><span class="m">12</span><span class="w"> </span>/<span class="w"> </span><span class="m">200</span><span class="o">]</span>
|
||
<span class="w"> </span><span class="p">|</span>><span class="w"> </span>firefox<span class="w"> </span><span class="m">1</span>.2.3<span class="w"> </span><span class="o">[</span><span class="c1">#########> ] 10Mb/s | 2min left</span>
|
||
<span class="w"> </span>Building<span class="w"> </span><span class="o">[</span><span class="m">2</span><span class="w"> </span>/<span class="w"> </span><span class="m">20</span><span class="o">]</span>
|
||
<span class="w"> </span><span class="p">|</span>><span class="w"> </span>glibc<span class="w"> </span><span class="m">1</span>.2.3<span class="w"> </span>-><span class="w"> </span>buildPhase:<span class="w"> </span><last<span class="w"> </span>log<span class="w"> </span>line>
|
||
------------------------------------------------------------------------
|
||
</code></pre></div>
|
||
<p>Now <strong>Learn</strong> part of the output is where you educate users. You should only
|
||
show it when you know that a build will take some time and not annoy users of
|
||
the builds that take only few seconds.</p>
|
||
<p>Every feature like this should go through an intensive review and testing to
|
||
collect as much feedback as possible and to fine tune every little detail. If
|
||
done right this can be an awesome features beginners and advance users will
|
||
love, but if not done perfectly it will annoy users and leave bad impression.</p>
|
||
<h2 id="input">Input</h2>
|
||
<p>Input to a command is provided via <code>ARGUMENTS</code> and <code>OPTIONS</code>.</p>
|
||
<p><code>ARGUMENTS</code> represent a required input for a function. When choosing to use
|
||
<code>ARGUMENTS</code> over <code>OPTIONS</code> please be aware of the downsides that come with it:</p>
|
||
<ul>
|
||
<li>User will need to remember the order of <code>ARGUMENTS</code>. This is not a problem if
|
||
there is only one <code>ARGUMENT</code>.</li>
|
||
<li>With <code>OPTIONS</code> it is possible to provide much better auto completion.</li>
|
||
<li>With <code>OPTIONS</code> it is possible to provide much better error message.</li>
|
||
<li>Using <code>OPTIONS</code> it will mean there is a little bit more typing.</li>
|
||
</ul>
|
||
<p>We don’t discourage the use of <code>ARGUMENTS</code>, but simply want to make every
|
||
developer consider the downsides and choose wisely.</p>
|
||
<h3 id="naming-the-options">Naming the <code>OPTIONS</code></h3>
|
||
<p>The only naming convention - apart from the ones mentioned in Naming the
|
||
<code>COMMANDS</code> section is how flags are named.</p>
|
||
<p>Flags are a type of <code>OPTION</code> that represent an option that can be turned ON of
|
||
OFF. We can say <strong>flags are boolean type of</strong> <code>**OPTION**</code>.</p>
|
||
<p>Here are few examples of flag <code>OPTIONS</code>:</p>
|
||
<ul>
|
||
<li><code>--colors</code> vs. <code>--no-colors</code> (showing colors in the output)</li>
|
||
<li><code>--emojis</code> vs. <code>--no-emojis</code> (showing emojis in the output)</li>
|
||
</ul>
|
||
<h3 id="prompt-when-input-not-provided">Prompt when input not provided</h3>
|
||
<p>For <em>main commands</em> (as <a href="#classification">per classification</a>) we want command
|
||
to improve the discoverability of possible input. A new user will most likely
|
||
not know which <code>ARGUMENTS</code> and <code>OPTIONS</code> are required or which values are
|
||
possible for those options.</p>
|
||
<p>In case the user does not provide the input or they provide wrong input,
|
||
rather than show the error, prompt a user with an option to find and select
|
||
correct input (see examples).</p>
|
||
<p>Prompting is of course not required when TTY is not attached to STDIN. This
|
||
would mean that scripts won't need to handle prompt, but rather handle errors.</p>
|
||
<p>A place to use prompt and provide user with interactive select</p>
|
||
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>nix<span class="w"> </span>init
|
||
Initializing<span class="w"> </span>Nix<span class="w"> </span>project<span class="w"> </span>at<span class="w"> </span><span class="sb">`</span>/path/to/here<span class="sb">`</span>.
|
||
<span class="w"> </span>Select<span class="w"> </span>a<span class="w"> </span>template<span class="w"> </span><span class="k">for</span><span class="w"> </span>you<span class="w"> </span>new<span class="w"> </span>project:
|
||
<span class="w"> </span><span class="p">|</span>><span class="w"> </span>py
|
||
<span class="w"> </span>template#python-pip
|
||
<span class="w"> </span>template#python-poetry
|
||
<span class="w"> </span><span class="o">[</span><span class="w"> </span>Showing<span class="w"> </span><span class="m">2</span><span class="w"> </span>templates<span class="w"> </span>from<span class="w"> </span><span class="m">1345</span><span class="w"> </span>templates<span class="w"> </span><span class="o">]</span>
|
||
</code></pre></div>
|
||
<p>Another great place to add prompts are <strong>confirmation dialogues for dangerous
|
||
actions</strong>. For example when adding new substitutor via <code>OPTIONS</code> or via
|
||
<code>flake.nix</code> we should prompt - for the first time - and let user review what is
|
||
going to happen.</p>
|
||
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>nix<span class="w"> </span>build<span class="w"> </span>--option<span class="w"> </span>substitutors<span class="w"> </span>https://cache.example.org
|
||
------------------------------------------------------------------------
|
||
<span class="w"> </span>Warning!<span class="w"> </span>A<span class="w"> </span>security<span class="w"> </span>related<span class="w"> </span>question<span class="w"> </span>needs<span class="w"> </span>to<span class="w"> </span>be<span class="w"> </span>answered.
|
||
------------------------------------------------------------------------
|
||
<span class="w"> </span>The<span class="w"> </span>following<span class="w"> </span>substitutors<span class="w"> </span>will<span class="w"> </span>be<span class="w"> </span>used<span class="w"> </span>to<span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="sb">`</span>my-project<span class="sb">`</span>:
|
||
<span class="w"> </span>-<span class="w"> </span>https://cache.example.org
|
||
|
||
<span class="w"> </span>Do<span class="w"> </span>you<span class="w"> </span>allow<span class="w"> </span><span class="sb">`</span>my-project<span class="sb">`</span><span class="w"> </span>to<span class="w"> </span>use<span class="w"> </span>above<span class="w"> </span>mentioned<span class="w"> </span>substitutors?
|
||
<span class="w"> </span><span class="o">[</span>y/N<span class="o">]</span><span class="w"> </span><span class="p">|</span>><span class="w"> </span>y
|
||
</code></pre></div>
|
||
<h2 id="output">Output</h2>
|
||
<p>Terminal output can be quite limiting in many ways. Which should force us to
|
||
think about the experience even more. As with every design the output is a
|
||
compromise between being terse and being verbose, between showing help to
|
||
beginners and annoying advance users. For this it is important that we know
|
||
what are the priorities.</p>
|
||
<p>Lix command line should be first and foremost written with beginners in mind.
|
||
But users won't stay beginners for long and what was once useful might quickly
|
||
become annoying. There is no golden rule that we can give in this guideline
|
||
that would make it easier how to draw a line and find best compromise.</p>
|
||
<p>What we would encourage is to <strong>build prototypes</strong>, do some <strong>user testing</strong>
|
||
and collect <strong>feedback</strong>. Then repeat the cycle few times.</p>
|
||
<p>First design the <em>happy path</em> and only after your iron it out, continue to work
|
||
on <strong>edge cases</strong> (handling and displaying errors, changes of the output by
|
||
certain <code>OPTIONS</code>, etc…)</p>
|
||
<h3 id="follow-best-practices">Follow best practices</h3>
|
||
<p>Needless to say we Lix must be a good citizen and follow best practices in
|
||
command line.</p>
|
||
<p>In short: <strong>STDOUT is for output, STDERR is for (human) messaging.</strong></p>
|
||
<p>STDOUT and STDERR provide a way for you to output messages to the user while
|
||
also allowing them to redirect content to a file. For example:</p>
|
||
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>nix<span class="w"> </span>build<span class="w"> </span>><span class="w"> </span>build.txt
|
||
------------------------------------------------------------------------
|
||
<span class="w"> </span>Error!<span class="w"> </span>Attribute<span class="w"> </span><span class="sb">`</span>bin<span class="sb">`</span><span class="w"> </span>missing<span class="w"> </span>at<span class="w"> </span><span class="o">(</span><span class="m">1</span>:94<span class="o">)</span><span class="w"> </span>from<span class="w"> </span>string.
|
||
------------------------------------------------------------------------
|
||
|
||
<span class="w"> </span><span class="m">1</span><span class="p">|</span><span class="w"> </span>with<span class="w"> </span>import<span class="w"> </span><nixpkgs><span class="w"> </span><span class="o">{</span><span class="w"> </span><span class="o">}</span><span class="p">;</span><span class="w"> </span><span class="o">(</span>pkgs.runCommandCC<span class="w"> </span>or<span class="w"> </span>pkgs.runCommand<span class="o">)</span><span class="w"> </span><span class="s2">"shell"</span><span class="w"> </span><span class="o">{</span><span class="w"> </span><span class="nv">buildInputs</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">[</span><span class="w"> </span><span class="o">(</span>surge.bin<span class="o">)</span><span class="w"> </span><span class="o">]</span><span class="p">;</span><span class="w"> </span><span class="o">}</span><span class="w"> </span><span class="s2">""</span>
|
||
</code></pre></div>
|
||
<p>Because this warning is on STDERR, it doesn’t end up in the file.</p>
|
||
<p>But not everything on STDERR is an error though. For example, you can run <code>nix
|
||
build</code> and collect logs in a file while still seeing the progress.</p>
|
||
<div class="highlight"><pre><span></span><code>$ nix build > build.txt
|
||
Evaluated 1234 files in 1.2 seconds
|
||
Downloaded python3.8-poetry 1.2.3 in 5.3 seconds
|
||
Downloaded python3.8-requests 1.2.3 in 5.3 seconds
|
||
------------------------------------------------------------------------
|
||
Press `v` to increase logs verbosity
|
||
|> `?` to see other options
|
||
------------------------------------------------------------------------
|
||
Learn something new with every build...
|
||
|> See last logs of a build with `nix log --last` command.
|
||
------------------------------------------------------------------------
|
||
Evaluated my-project 1.2.3 in 14.43 seconds
|
||
Downloading [12 / 200]
|
||
|> firefox 1.2.3 [#########> ] 10Mb/s | 2min left
|
||
Building [2 / 20]
|
||
|> glibc 1.2.3 -> buildPhase: <last log line>
|
||
------------------------------------------------------------------------
|
||
</code></pre></div>
|
||
<h3 id="errors-wip">Errors (WIP)</h3>
|
||
<p><strong>TODO</strong>: Once we have implementation for the <em>happy path</em> then we will think
|
||
how to present errors.</p>
|
||
<h3 id="not-only-for-humans">Not only for humans</h3>
|
||
<p>Terse, machine-readable output formats can also be useful but shouldn’t get in
|
||
the way of making beautiful CLI output. When needed, commands should offer a
|
||
<code>--json</code> flag to allow users to easily parse and script the CLI.</p>
|
||
<p>When TTY is not detected on STDOUT we should remove all design elements (no
|
||
colors, no emojis and using ASCII instead of Unicode symbols). The same should
|
||
happen when TTY is not detected on STDERR. We should not display progress /
|
||
status section, but only print warnings and errors.</p>
|
||
<h3 id="returning-future-proof-json">Returning future proof JSON</h3>
|
||
<p>The schema of JSON output should allow for backwards compatible extension. This section explains how to achieve this.</p>
|
||
<p>Two definitions are helpful here, because while JSON only defines one "key-value"
|
||
object type, we use it to cover two use cases:</p>
|
||
<ul>
|
||
<li><strong>dictionary</strong>: a map from names to value that all have the same type. In
|
||
C++ this would be a <code>std::map</code> with string keys.</li>
|
||
<li><strong>record</strong>: a fixed set of attributes each with their own type. In C++, this
|
||
would be represented by a <code>struct</code>.</li>
|
||
</ul>
|
||
<p>It is best not to mix these use cases, as that may lead to incompatibilities when the schema changes. For example, adding a record field to a dictionary breaks consumers that assume all JSON object fields to have the same meaning and type.</p>
|
||
<p>This leads to the following guidelines:</p>
|
||
<ul>
|
||
<li>The top-level (root) value must be a record.</li>
|
||
</ul>
|
||
<p>Otherwise, one can not change the structure of a command's output.</p>
|
||
<ul>
|
||
<li>The value of a dictionary item must be a record.</li>
|
||
</ul>
|
||
<p>Otherwise, the item type can not be extended.</p>
|
||
<ul>
|
||
<li>List items should be records.</li>
|
||
</ul>
|
||
<p>Otherwise, one can not change the structure of the list items.</p>
|
||
<p>If the order of the items does not matter, and each item has a unique key that is a string, consider representing the list as a dictionary instead. If the order of the items needs to be preserved, return a list of records.</p>
|
||
<ul>
|
||
<li>Streaming JSON should return records.</li>
|
||
</ul>
|
||
<p>An example of a streaming JSON format is <a href="https://jsonlines.org/">JSON lines</a>, where each line represents a JSON value. These JSON values can be considered top-level values or list items, and they must be records.</p>
|
||
<h4 id="examples">Examples</h4>
|
||
<p>This is bad, because all keys must be assumed to be store implementations:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"local"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"remote"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"http"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>This is good, because the it is extensible at the root, and is somewhat self-documenting:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
||
<span class="w"> </span><span class="nt">"storeTypes"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"local"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">},</span>
|
||
<span class="w"> </span><span class="nt">"pluginSupport"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
||
<span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>While the dictionary of store types seems like a very complete response at first, a use case may arise that warrants returning additional information.
|
||
For example, the presence of plugin support may be crucial information for a client to proceed when their desired store type is missing.</p>
|
||
<p>The following representation is bad because it is not extensible:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span><span class="w"> </span><span class="nt">"outputs"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"out"</span><span class="w"> </span><span class="s2">"bin"</span><span class="w"> </span><span class="p">]</span><span class="w"> </span><span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>However, simply converting everything to records is not enough, because the order of outputs must be preserved:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span><span class="w"> </span><span class="nt">"outputs"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"bin"</span><span class="p">:</span><span class="w"> </span><span class="p">{},</span><span class="w"> </span><span class="nt">"out"</span><span class="p">:</span><span class="w"> </span><span class="p">{}</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span>
|
||
</code></pre></div>
|
||
<p>The first item is the default output. Deriving this information from the outputs ordering is not great, but this is how Lix currently happens to work.
|
||
While it is possible for a JSON parser to preserve the order of fields, we can not rely on this capability to be present in all JSON libraries.</p>
|
||
<p>This representation is extensible and preserves the ordering:</p>
|
||
<div class="highlight"><pre><span></span><code><span class="p">{</span><span class="w"> </span><span class="nt">"outputs"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"outputName"</span><span class="p">:</span><span class="w"> </span><span class="s2">"out"</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"outputName"</span><span class="p">:</span><span class="w"> </span><span class="s2">"bin"</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">]</span><span class="w"> </span><span class="p">}</span>
|
||
</code></pre></div>
|
||
<h3 id="dialog-with-the-user">Dialog with the user</h3>
|
||
<p>CLIs don't always make it clear when an action has taken place. For every
|
||
action a user performs, your CLI should provide an equal and appropriate
|
||
reaction, clearly highlighting the what just happened. For example:</p>
|
||
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>nix<span class="w"> </span>build
|
||
<span class="w"> </span>Downloaded<span class="w"> </span>python3.8-poetry<span class="w"> </span><span class="m">1</span>.2.3<span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="m">5</span>.3<span class="w"> </span>seconds
|
||
<span class="w"> </span>Downloaded<span class="w"> </span>python3.8-requests<span class="w"> </span><span class="m">1</span>.2.3<span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="m">5</span>.3<span class="w"> </span>seconds
|
||
...
|
||
<span class="w"> </span>Success!<span class="w"> </span>You<span class="w"> </span>have<span class="w"> </span>successfully<span class="w"> </span>built<span class="w"> </span>my-project.
|
||
$
|
||
</code></pre></div>
|
||
<p>Above command clearly states that command successfully completed. And in case
|
||
of <code>nix build</code>, which is a command that might take some time to complete, it is
|
||
equally important to also show that a command started.</p>
|
||
<h3 id="text-alignment">Text alignment</h3>
|
||
<p>Text alignment is the number one design element that will present all of the
|
||
Nix commands as a family and not as separate tools glued together.</p>
|
||
<p>The format we should follow is:</p>
|
||
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>nix<span class="w"> </span>COMMAND
|
||
<span class="w"> </span>VERB_1<span class="w"> </span>NOUN<span class="w"> </span>and<span class="w"> </span>other<span class="w"> </span>words
|
||
<span class="w"> </span>VERB__1<span class="w"> </span>NOUN<span class="w"> </span>and<span class="w"> </span>other<span class="w"> </span>words
|
||
<span class="w"> </span><span class="p">|</span>><span class="w"> </span>Some<span class="w"> </span>details
|
||
</code></pre></div>
|
||
<p>Few rules that we can extract from above example:</p>
|
||
<ul>
|
||
<li>Each line should start at least with one space.</li>
|
||
<li>First word should be a VERB and must be aligned to the right.</li>
|
||
<li>Second word should be a NOUN and must be aligned to the left.</li>
|
||
<li>If you can not find a good VERB / NOUN pair, don’t worry make it as
|
||
understandable to the user as possible.</li>
|
||
<li>More details of each line can be provided by <code>|></code> character which is serving
|
||
as the first word when aligning the text</li>
|
||
</ul>
|
||
<p>Don’t forget you should also test your terminal output with colors and emojis
|
||
off (<code>--no-colors --no-emojis</code>).</p>
|
||
<h3 id="dim-bright">Dim / Bright</h3>
|
||
<p>After comparing few terminals with different color schemes we would <strong>recommend
|
||
to avoid using dimmed text</strong>. The difference from the rest of the text is very
|
||
little in many terminal and color scheme combinations. Sometimes the difference
|
||
is not even notable, therefore relying on it wouldn’t make much sense.</p>
|
||
<p><strong>The bright text is much better supported</strong> across terminals and color
|
||
schemes. Most of the time the difference is perceived as if the bright text
|
||
would be bold.</p>
|
||
<h3 id="colors">Colors</h3>
|
||
<p>Humans are already conditioned by society to attach certain meaning to certain
|
||
colors. While the meaning is not universal, a simple collection of colors is
|
||
used to represent basic emotions.</p>
|
||
<p>Colors that can be used in output</p>
|
||
<ul>
|
||
<li>Red = error, danger, stop</li>
|
||
<li>Green = success, good</li>
|
||
<li>Yellow/Orange = proceed with caution, warning, in progress</li>
|
||
<li>Blue/Magenta = stability, calm</li>
|
||
</ul>
|
||
<p>While colors are nice, when command line is used by machines (in automation
|
||
scripts) you want to remove the colors. There should be a global <code>--no-colors</code>
|
||
option that would remove the colors.</p>
|
||
<h3 id="special-unicode-characters">Special (Unicode) characters</h3>
|
||
<p>Most of the terminal have good support for Unicode characters and you should
|
||
use them in your output by default. But always have a backup solution that is
|
||
implemented only with ASCII characters and will be used when <code>--ascii</code> option
|
||
is going to be passed in. Please make sure that you test your output also
|
||
without Unicode characters</p>
|
||
<p>More they showing all the different Unicode characters it is important to
|
||
<strong>establish common set of characters</strong> that we use for certain situations.</p>
|
||
<h3 id="emojis">Emojis</h3>
|
||
<p>Emojis help channel emotions even better than text, colors and special
|
||
characters.</p>
|
||
<p>We recommend <strong>keeping the set of emojis to a minimum</strong>. This will enable each
|
||
emoji to stand out more.</p>
|
||
<p>As not everybody is happy about emojis we should provide an <code>--no-emojis</code>
|
||
option to disable them. Please make sure that you test your output also without
|
||
emojis.</p>
|
||
<h3 id="tables">Tables</h3>
|
||
<p>All commands that are listing certain data can be implemented in some sort of a
|
||
table. It’s important that each row of your output is a single ‘entry’ of data.
|
||
Never output table borders. It’s noisy and a huge pain for parsing using other
|
||
tools such as <code>grep</code>.</p>
|
||
<p>Be mindful of the screen width. Only show a few columns by default with the
|
||
table header, for more the table can be manipulated by the following options:</p>
|
||
<ul>
|
||
<li><code>--no-headers</code>: Show column headers by default but allow to hide them.</li>
|
||
<li><code>--columns</code>: Comma-separated list of column names to add.</li>
|
||
<li><code>--sort</code>: Allow sorting by column. Allow inverse and multi-column sort as well.</li>
|
||
</ul>
|
||
<h3 id="interactive-output">Interactive output</h3>
|
||
<p>Interactive output was selected to be able to strike the balance between
|
||
beginners and advance users. While the default output will target beginners it
|
||
can, with a few key strokes, be changed into and advance introspection tool.</p>
|
||
<h4 id="progress">Progress</h4>
|
||
<p>For longer running commands we should provide and overview the progress.
|
||
This is shown best in <code>nix build</code> example:</p>
|
||
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>nix<span class="w"> </span>build
|
||
<span class="w"> </span>Started<span class="w"> </span>building<span class="w"> </span>my-project<span class="w"> </span><span class="m">1</span>.2.3
|
||
<span class="w"> </span>Downloaded<span class="w"> </span>python3.8-poetry<span class="w"> </span><span class="m">1</span>.2.3<span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="m">5</span>.3<span class="w"> </span>seconds
|
||
<span class="w"> </span>Downloaded<span class="w"> </span>python3.8-requests<span class="w"> </span><span class="m">1</span>.2.3<span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="m">5</span>.3<span class="w"> </span>seconds
|
||
------------------------------------------------------------------------
|
||
<span class="w"> </span>Press<span class="w"> </span><span class="sb">`</span>v<span class="sb">`</span><span class="w"> </span>to<span class="w"> </span>increase<span class="w"> </span>logs<span class="w"> </span>verbosity
|
||
<span class="w"> </span><span class="p">|</span>><span class="w"> </span><span class="sb">`</span>?<span class="sb">`</span><span class="w"> </span>to<span class="w"> </span>see<span class="w"> </span>other<span class="w"> </span>options
|
||
------------------------------------------------------------------------
|
||
<span class="w"> </span>Learn<span class="w"> </span>something<span class="w"> </span>new<span class="w"> </span>with<span class="w"> </span>every<span class="w"> </span>build...
|
||
<span class="w"> </span><span class="p">|</span>><span class="w"> </span>See<span class="w"> </span>last<span class="w"> </span>logs<span class="w"> </span>of<span class="w"> </span>a<span class="w"> </span>build<span class="w"> </span>with<span class="w"> </span><span class="sb">`</span>nix<span class="w"> </span>log<span class="w"> </span>--last<span class="sb">`</span><span class="w"> </span>command.
|
||
------------------------------------------------------------------------
|
||
<span class="w"> </span>Evaluated<span class="w"> </span>my-project<span class="w"> </span><span class="m">1</span>.2.3<span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="m">14</span>.43<span class="w"> </span>seconds
|
||
Downloading<span class="w"> </span><span class="o">[</span><span class="m">12</span><span class="w"> </span>/<span class="w"> </span><span class="m">200</span><span class="o">]</span>
|
||
<span class="w"> </span><span class="p">|</span>><span class="w"> </span>firefox<span class="w"> </span><span class="m">1</span>.2.3<span class="w"> </span><span class="o">[</span><span class="c1">#########> ] 10Mb/s | 2min left</span>
|
||
<span class="w"> </span>Building<span class="w"> </span><span class="o">[</span><span class="m">2</span><span class="w"> </span>/<span class="w"> </span><span class="m">20</span><span class="o">]</span>
|
||
<span class="w"> </span><span class="p">|</span>><span class="w"> </span>glibc<span class="w"> </span><span class="m">1</span>.2.3<span class="w"> </span>-><span class="w"> </span>buildPhase:<span class="w"> </span><last<span class="w"> </span>log<span class="w"> </span>line>
|
||
------------------------------------------------------------------------
|
||
</code></pre></div>
|
||
<h4 id="search">Search</h4>
|
||
<p>Use a <code>fzf</code> like fuzzy search when there are multiple options to choose from.</p>
|
||
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>nix<span class="w"> </span>init
|
||
Initializing<span class="w"> </span>Nix<span class="w"> </span>project<span class="w"> </span>at<span class="w"> </span><span class="sb">`</span>/path/to/here<span class="sb">`</span>.
|
||
<span class="w"> </span>Select<span class="w"> </span>a<span class="w"> </span>template<span class="w"> </span><span class="k">for</span><span class="w"> </span>you<span class="w"> </span>new<span class="w"> </span>project:
|
||
<span class="w"> </span><span class="p">|</span>><span class="w"> </span>py
|
||
<span class="w"> </span>template#python-pip
|
||
<span class="w"> </span>template#python-poetry
|
||
<span class="w"> </span><span class="o">[</span><span class="w"> </span>Showing<span class="w"> </span><span class="m">2</span><span class="w"> </span>templates<span class="w"> </span>from<span class="w"> </span><span class="m">1345</span><span class="w"> </span>templates<span class="w"> </span><span class="o">]</span>
|
||
</code></pre></div>
|
||
<h4 id="prompt">Prompt</h4>
|
||
<p>In some situations we need to prompt the user and inform the user about what is
|
||
going to happen.</p>
|
||
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>nix<span class="w"> </span>build<span class="w"> </span>--option<span class="w"> </span>substitutors<span class="w"> </span>https://cache.example.org
|
||
------------------------------------------------------------------------
|
||
<span class="w"> </span>Warning!<span class="w"> </span>A<span class="w"> </span>security<span class="w"> </span>related<span class="w"> </span>question<span class="w"> </span>needs<span class="w"> </span>to<span class="w"> </span>be<span class="w"> </span>answered.
|
||
------------------------------------------------------------------------
|
||
<span class="w"> </span>The<span class="w"> </span>following<span class="w"> </span>substitutors<span class="w"> </span>will<span class="w"> </span>be<span class="w"> </span>used<span class="w"> </span>to<span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="sb">`</span>my-project<span class="sb">`</span>:
|
||
<span class="w"> </span>-<span class="w"> </span>https://cache.example.org
|
||
|
||
<span class="w"> </span>Do<span class="w"> </span>you<span class="w"> </span>allow<span class="w"> </span><span class="sb">`</span>my-project<span class="sb">`</span><span class="w"> </span>to<span class="w"> </span>use<span class="w"> </span>above<span class="w"> </span>mentioned<span class="w"> </span>substitutors?
|
||
<span class="w"> </span><span class="o">[</span>y/N<span class="o">]</span><span class="w"> </span><span class="p">|</span>><span class="w"> </span>y
|
||
</code></pre></div>
|
||
<h3 id="verbosity">Verbosity</h3>
|
||
<p>There are many ways that you can control verbosity.</p>
|
||
<p>Verbosity levels are:</p>
|
||
<ul>
|
||
<li><code>ERROR</code> (level 0)</li>
|
||
<li><code>WARN</code> (level 1)</li>
|
||
<li><code>NOTICE</code> (level 2)</li>
|
||
<li><code>INFO</code> (level 3)</li>
|
||
<li><code>TALKATIVE</code> (level 4)</li>
|
||
<li><code>CHATTY</code> (level 5)</li>
|
||
<li><code>DEBUG</code> (level 6)</li>
|
||
<li><code>VOMIT</code> (level 7)</li>
|
||
</ul>
|
||
<p>The default level that the command starts is <code>ERROR</code>. The simplest way to
|
||
increase the verbosity by stacking <code>-v</code> option (eg: <code>-vvv == level 3 == INFO</code>).
|
||
There are also two shortcuts, <code>--debug</code> to run in <code>DEBUG</code> verbosity level and
|
||
<code>--quiet</code> to run in <code>ERROR</code> verbosity level.</p>
|
||
<hr />
|
||
<h2 id="appendix-1-commands-naming-exceptions">Appendix 1: Commands naming exceptions</h2>
|
||
<p><code>nix init</code> and <code>nix repl</code> are well established</p>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</article>
|
||
</div>
|
||
|
||
|
||
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
|
||
</div>
|
||
|
||
</main>
|
||
|
||
<footer class="md-footer">
|
||
|
||
<div class="md-footer-meta md-typeset">
|
||
<div class="md-footer-meta__inner md-grid">
|
||
<div class="md-copyright">
|
||
|
||
<div class="md-copyright__highlight">
|
||
Licenced MIT
|
||
</div>
|
||
|
||
|
||
Made with
|
||
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
|
||
Material for MkDocs
|
||
</a>
|
||
|
||
</div>
|
||
|
||
<div class="md-social">
|
||
|
||
|
||
|
||
|
||
|
||
<a href="https://git.auxolotl.org/auxolotl/docs" target="_blank" rel="noopener" title="Aux Docs Repo" class="md-social__link">
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M16.777 0a2.9 2.9 0 1 1-2.529 4.322H12.91a4.266 4.266 0 0 0-4.265 4.195v2.118a7.076 7.076 0 0 1 4.147-1.42l.118-.002h1.338a2.9 2.9 0 0 1 5.43 1.422 2.9 2.9 0 0 1-5.43 1.422H12.91a4.266 4.266 0 0 0-4.265 4.195v2.319A2.9 2.9 0 0 1 7.222 24 2.9 2.9 0 0 1 5.8 18.57V8.589a7.109 7.109 0 0 1 6.991-7.108l.118-.001h1.338A2.9 2.9 0 0 1 16.778 0ZM7.223 19.905a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Zm9.554-10.464a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.39Zm0-7.735a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Z"/></svg>
|
||
</a>
|
||
|
||
|
||
|
||
|
||
|
||
<a href="https://forum.aux.computer/" target="_blank" rel="noopener" title="Aux Forum" class="md-social__link">
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12.103 0C18.666 0 24 5.485 24 11.997c0 6.51-5.33 11.99-11.9 11.99L0 24V11.79C0 5.28 5.532 0 12.103 0zm.116 4.563a7.395 7.395 0 0 0-6.337 3.57 7.247 7.247 0 0 0-.148 7.22L4.4 19.61l4.794-1.074a7.424 7.424 0 0 0 8.136-1.39 7.256 7.256 0 0 0 1.737-7.997 7.375 7.375 0 0 0-6.84-4.585h-.008z"/></svg>
|
||
</a>
|
||
|
||
|
||
|
||
|
||
|
||
<a href="https://wiki.auxolotl.org/" target="_blank" rel="noopener" title="Aux Wiki" class="md-social__link">
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M17.801 13.557c.148.098.288.202.417.313 1.854 1.6 3.127 4.656 2.582 7.311-1.091-.255-5.747-1.055-7.638-3.383-.91-1.12-1.366-2.081-1.569-2.885a5.65 5.65 0 0 0 .034-.219c.089.198.197.35.313.466.24.24.521.335.766.372.304.046.594-.006.806-.068l.001.001c.05-.015.433-.116.86-.342.325-.173 2.008-.931 3.428-1.566Zm-7.384 1.435C9.156 16.597 6.6 18.939.614 18.417c.219-1.492 1.31-3.019 2.51-4.11.379-.345.906-.692 1.506-1.009.286.168.598.332.939.486 2.689 1.221 3.903 1.001 4.89.573a1.3 1.3 0 0 0 .054-.025 6.156 6.156 0 0 0-.096.66Zm4.152-.462c.38-.341.877-.916 1.383-1.559-.389-.15-.866-.371-1.319-.591-.598-.29-1.305-.283-2.073-.315a4.685 4.685 0 0 1-.804-.103c.014-.123.027-.246.038-.369.062.104.673.057.871.057.354 0 1.621.034 3.074-.574 1.452-.608 2.55-1.706 3.022-3.225.474-1.52.22-3.091-.168-3.952-.169.709-1.453 2.381-1.926 2.871-.473.489-2.381 2.296-2.972 2.921-.7.74-.688.793-1.332 1.302-.202.19-.499.402-.563.53.027-.338.039-.675.027-.997a7.653 7.653 0 0 0-.032-.523c.322-.059.567-.522.567-.861 0-.224-.106-.247-.271-.229.075-.894.382-3.923 1.254-4.281.218.109.831.068.649-.295-.182-.364-.825-.074-1.081.266-.28.374-.956 2.046-.92 4.324-.113.014-.174.033-.322.033-.171 0-.321-.04-.433-.05.034-2.275-.714-3.772-.84-4.169-.12-.375-.491-.596-.781-.596-.146 0-.272.056-.333.179-.182.363.459.417.677.308.706.321 1.156 3.519 1.254 4.277-.125-.006-.199.035-.199.233 0 .311.17.756.452.843a.442.442 0 0 0-.007.03s-.287.99-.413 2.189a4.665 4.665 0 0 1-.718-.225c-.714-.286-1.355-.583-2.019-.566-.664.018-1.366.023-1.804-.036-.438-.058-.649-.15-.649-.15s-.234.365.257 1.075c.42.607 1.055 1.047 1.644 1.18.589.134 1.972.18 2.785-.377.16-.109.317-.228.459-.34a8.717 8.717 0 0 0-.013.626c-.289.753-.571 1.993-.268 3.338 0-.001.701-.842.787-2.958.006-.144.009-.271.01-.383.052-.248.103-.518.148-.799.072.135.151.277.234.413.511.842 1.791 1.37 2.383 1.49.091.019.187.032.285.038Zm-1.12.745c-.188.055-.445.1-.713.059-.21-.031-.45-.11-.655-.316-.169-.168-.312-.419-.401-.789a9.837 9.837 0 0 0 .039-.82l.049-.243c.563.855 1.865 1.398 2.476 1.522.036.008.072.014.109.02l-.013.009c-.579.415-.76.503-.891.558Zm6.333-2.818c-.257.114-4.111 1.822-5.246 2.363.98-.775 3.017-3.59 3.699-4.774 1.062.661 1.468 1.109 1.623 1.441.101.217.09.38.096.515a.57.57 0 0 1-.172.455Zm-9.213 1.62a1.606 1.606 0 0 1-.19.096c-.954.414-2.126.61-4.728-.571-2.023-.918-3.024-2.157-3.371-2.666.476.161 1.471.473 2.157.524.282.021.703.068 1.167.125.021.209.109.486.345.829l.001.001c.451.651 1.134 1.119 1.765 1.262.622.141 2.083.182 2.942-.407a3.12 3.12 0 0 0 .132-.093l.001.179a6.052 6.052 0 0 0-.221.721Zm5.512-1.271a17.49 17.49 0 0 1-1.326-.589c.437.042 1.054.083 1.692.108-.121.162-.244.323-.366.481Zm.932-1.26c-.12.17-.245.343-.373.517-.241.018-.478.03-.709.038a29.05 29.05 0 0 1-.741-.048c.608-.065 1.228-.252 1.823-.507Zm.22-.315c-.809.382-1.679.648-2.507.648-.472 0-.833.018-1.139.039v.001c-.324-.031-.665-.039-1.019-.054a3.555 3.555 0 0 1-.152-.009c.102-.002.192-.006.249-.006.363 0 1.662.034 3.151-.589 1.508-.632 2.645-1.773 3.136-3.351.37-1.186.31-2.402.086-3.312.458-.336.86-.651 1.147-.91.501-.451.743-.733.848-.869.199.206.714.864.685 2.138-.036 1.611-.606 3.187-1.501 4.154a9.099 9.099 0 0 1-1.321 1.132 11.978 11.978 0 0 0-.644-.422l-.089-.055-.051.091c-.184.332-.5.825-.879 1.374ZM4.763 5.817c-.157 1.144.113 2.323.652 3.099.539.776 2.088 2.29 3.614 2.505.991.14 2.055.134 2.055.134s-.593-.576-1.114-1.66c-.521-1.085-.948-2.104-1.734-2.786-.785-.681-1.601-1.416-2.045-1.945-.444-.53-.59-.86-.59-.86s-.656.175-.838 1.513Zm14.301 4.549a9.162 9.162 0 0 0 1.3-1.12c.326-.352.611-.782.845-1.265 1.315.145 2.399.371 2.791.434 0 0-.679 1.971-3.945 3.022l-.016-.035c-.121-.26-.385-.594-.975-1.036Zm-11.634.859a8.537 8.537 0 0 1-.598-.224c-1.657-.693-2.91-1.944-3.449-3.678-.498-1.601-.292-3.251.091-4.269.225.544.758 1.34 1.262 2.01a3.58 3.58 0 0 0-.172.726c-.163 1.197.123 2.428.687 3.24.416.599 1.417 1.62 2.555 2.193-.128.002-.253.003-.376.002Zm-1.758-.077c-.958-.341-1.901-.787-2.697-1.368C-.07 7.559 0 6.827 0 6.827s1.558-.005 3.088.179c.03.126.065.251.104.377.557 1.791 1.851 3.086 3.562 3.803l.047.019a4.254 4.254 0 0 1-.267-.026h-.001c-.401-.053-.595-.135-.595-.135l-.157-.069-.092.144-.017.029Zm6.807-1.59c.086.017.136.058.136.145 0 .197-.242.5-.597.597l-.01-.161a.887.887 0 0 0 .283-.243c.078-.099.142-.217.188-.338Zm-1.591.006c.033.1.076.197.129.282.061.097.134.18.217.24l-.021.083c-.276-.093-.424-.293-.424-.466 0-.078.035-.119.099-.139Zm-.025-.664c-.275-.816-.795-2.022-1.505-2.179-.296.072-.938.096-.691-.145.246-.24 1.085-.048 1.283.217.145.194.744.806 1.011 1.737l.032.227a.324.324 0 0 0-.13.143Zm1.454-.266c.251-.99.889-1.639 1.039-1.841.197-.265 1.036-.457 1.283-.217.247.241-.395.217-.691.145-.69.152-1.2 1.296-1.481 2.109a.364.364 0 0 0-.067-.059.37.37 0 0 0-.092-.043l.009-.094Zm4.802-2.708a9.875 9.875 0 0 1-.596.705c-.304.315-1.203 1.176-1.963 1.916.647-.955 1.303-1.806 2.184-2.376.123-.08.249-.161.375-.245Z"/></svg>
|
||
</a>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
</footer>
|
||
|
||
</div>
|
||
<div class="md-dialog" data-md-component="dialog">
|
||
<div class="md-dialog__inner md-typeset"></div>
|
||
</div>
|
||
|
||
|
||
<script id="__config" type="application/json">{"base": "../../..", "features": ["content.tooltips", "search.highlight", "navigation.tabs", "navigation.indexes", "navigation.prune"], "search": "../../../assets/javascripts/workers/search.b8dbb3d2.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>
|
||
|
||
|
||
<script src="../../../assets/javascripts/bundle.fe8b6f2b.min.js"></script>
|
||
|
||
|
||
</body>
|
||
</html> |