quickstart.json

{"content":"<p>Once you have KBSecret <a href=\"/#/install/\">installed</a>, getting started is straightforward.</p>\n<h2 id=\"terminology\">Terminology</h2>\n<h3 id=\"the-basics\">The basics</h3>\n<p>KBSecret is a program that stores secrets. Your e-mail login and a personal to-do list are examples\nof secrets.</p>\n<p>KBSecret is also a program that <em>shares</em> secrets. Secrets can be shared with any other Keybase\nuser, and groups of users can add and modify secrets together.</p>\n<p>KBSecret aims to do both of the above with a minimum of fuss and thought: secrets are encrypted\ntransparently and shared instantly.</p>\n<h3 id=\"technical-specifics\">Technical specifics</h3>\n<p>KBSecret&#39;s documentation uses three key terms: <strong>types</strong>, <strong>records</strong>,\nand <strong>sessions</strong>.</p>\n<p>A <strong>type</strong> in KBSecret is a collection of fields and operations on those fields. For example,\nthe <code>login</code> type might have two fields (a <code>username</code> and <code>password</code>), and operations to update\nthose fields as necessary.</p>\n<p>A <strong>record</strong> in KBSecret is an instantiation of a <strong>type</strong>, meaning that its fields are bound to\nreal values. For example, if <code>gmail</code> were a record of type <code>login</code>, its <code>username</code> might be\nbound to <code>alice</code> and its <code>password</code> might be bound to <code>hunter2</code>.</p>\n<p>A <strong>session</strong> in KBSecret is a collection of <strong>records</strong>. Multiple types of records can be present\nin the session. Every session is <em>either</em> associated\nwith one or more Keybase users (including you), <em>or</em> with a\n<a href=\"https://keybase.io/blog/introducing-keybase-teams\">Keybase team</a>.</p>\n<p>There are other concepts in KBSecret that you&#39;ll discover later (like generators), but these\nthree are the only ones absolutely required to get started.</p>\n<h2 id=\"types\">Types</h2>\n<p>First, let&#39;s see what kinds of records we can create:</p>\n<pre><code class=\"language-bash\">$ kbsecret types</code></pre>\n<p>Example output:</p>\n<pre><code>todo\nlogin\nenvironment\nunstructured\nsnippet</code></pre><p>In a clean installation, these are KBSecret&#39;s default types.</p>\n<p>Users can add their own types by dropping Ruby classes in\n<code>/keybase/private/&lt;username&gt;/kbsecret/.config/record/</code>, and you should check out the\n<a href=\"/#/customize/\">customization</a> page for more info on that.</p>\n<h2 id=\"records\">Records</h2>\n<p>So, KBSecret knows about <code>login</code> records. Let&#39;s create one:</p>\n<pre><code class=\"language-bash\">$ kbsecret new login facebook</code></pre>\n<p>This will prompt you to input the fields expected by the <code>login</code> type, namely a\nusername and password:</p>\n<pre><code>Username? Alice\nPassword? ********</code></pre><p>Now, let&#39;s see what records we have:</p>\n<pre><code class=\"language-bash\">$ kbsecret list</code></pre>\n<p>Outputs:</p>\n<pre><code>facebook</code></pre><p>And to access the record itself, we can use either <code>kbsecret login</code> or <code>kbsecret pass</code>:</p>\n<pre><code class=\"language-bash\">$ kbsecret login facebook\n$ kbsecret pass facebook</code></pre>\n<p>Outputs:</p>\n<pre><code>Label: facebook\n    Username: Alice\n    Password: hunter2</code></pre><p>and</p>\n<pre><code>hunter2</code></pre><p>respectively.</p>\n<p>Try this out with some of the other types above, and see what you get! As a rule of thumb, the\npattern is <code>kbsecret new &lt;type&gt;</code> for record creation, and <code>kbsecret &lt;type&gt;</code> for typed record access.</p>\n<h2 id=\"sessions\">Sessions</h2>\n<p>But wait, where did the record(s) created above go? We didn&#39;t specify a session in either\n<code>kbsecret new</code> or <code>kbsecret list</code>!</p>\n<p>When you don&#39;t pass an explicit session (more on that in a sec), KBSecret\nwill assume that you wanted the default session.</p>\n<p>We can confirm this by observing that these have the same output:</p>\n<pre><code class=\"language-bash\">$ kbsecret list\n$ kbsecret list -s default</code></pre>\n<p>So, how do we create a new session? With <code>kbsecret session new</code>!</p>\n<p>For example, this will create a session between two Keybase users (&quot;alice&quot; and\n&quot;bob&quot;) named &quot;ultra-secret&quot;:</p>\n<pre><code class=\"language-bash\">$ kbsecret session new ultra-secret --root ultra-secret --users alice,bob\n$ # more briefly\n$ kbsecret session new ultra-secret -r ultra-secret -u alice,bob</code></pre>\n<p>Note that the session label and <code>--root</code>/<code>-r</code> option don&#39;t need to be the same &mdash;\nthe label is what identifies the session to other <code>kbsecret</code> commands, while the root\nis the directory that the session&#39;s storage directory. In this case, it gets expanded\nto <code>/keybase/private/alice,bob/kbsecret/ultra-secret/</code>.</p>\n<p>We can also create a <em>team-based</em> session via the <code>--team</code> option, which takes the name\nof a Keybase team that you already belong to:</p>\n<pre><code class=\"language-bash\">$ kbsecret session new api-keys --team megacorp.devs</code></pre>\n<p>Team-based sessions infer the session storage directory from label, so we don&#39;t need\nto pass a separate <code>--root</code> option.</p>\n<p>Now that we have a new session, we can pass it to (most) other commands via the\n<code>--session</code>/<code>-s</code> option:</p>\n<pre><code class=\"language-bash\">$ kbsecret new -s ultra-secret\n$ kbsecret list --session api-keys</code></pre>\n<p>Note that <code>--session</code>/<code>-s</code> is a subcommand option, not applied to <code>kbsecret</code> itself. In other words,\n<code>kbsecret --session ultra-secret list</code> won&#39;t work!</p>\n<h2 id=\"next-steps\">Next steps</h2>\n<p>That covers the basics of KBSecret&#39;s main primitives: types, records, and sessions.</p>\n<p>These examples demonstrate some of the most common operations, but there are plenty of other\ncommands and options that you&#39;ll find useful. Luckily, they&#39;re all documented in the\n<a href=\"/man/kbsecret.1\">manual pages</a>!</p>\n<h2 id=\"afternote\">Afternote</h2>\n<p>If this guide is outdated, didn&#39;t help, or wasn&#39;t clear enough, it&#39;s a bug. Help us out by filing\na report <a href=\"https://github.com/kbsecret/kbsecret.github.io/issues\">here</a>.</p>\n","data":{"layout":"default"},"isEmpty":false,"excerpt":""}