customize.json

{"content":"<h2 id=\"custom-commands\">Custom commands</h2>\n<p>The main <code>kbsecret</code> executable is modeled after <code>git</code> &mdash; it scans <code>$PATH</code>\nfor candidate commands of the form <code>kbsecret-foo</code>, and allows them to be executed as subcommands.</p>\n<p>Built-in and core commands are given precedence over commands found on the <code>$PATH</code>, but any name\nnot already taken by a built-in or core command can be used for a custom command:</p>\n<pre><code class=\"language-bash\">$ cat &gt; ~/bin/kbsecret-hello\n#!/usr/bin/env bash\n\necho &quot;hello kbsecret, from bash!&quot;\n^D\n\n$ chmod +x ~/bin/kbsecret-hello\n\n$ kbsecret hello\nhello kbsecret, from bash!</code></pre>\n<p>There are a few advantages to using custom <code>kbsecret-*</code> commands:</p>\n<ul>\n<li>Shell completions can properly suggest your command as a completion candidate, and your\ncommand will show up in <code>kbsecret help</code> and <code>kbsecret commands</code></li>\n<li>KBSecret will pass the user&#39;s configured defaults to your command, including any default\narguments the user wants to be respected</li>\n<li><code>kbsecret foo</code> just looks nice!</li>\n</ul>\n<p>The <a href=\"https://github.com/kbsecret/ext-cmds\">ext-cmds</a> repository has some examples of custom\ncommands.</p>\n<p>(Regardless of whether you name your custom command as above, you can still use the\n<code>KBSecret::CLI</code> class for convenience command writing in Ruby &mdash; see\n<a href=\"http://www.rubydoc.info/gems/kbsecret/\">the docs</a>).</p>\n<h2 id=\"command-configuration\">Command configuration</h2>\n<p><strong>IMPORTANT</strong>: Versions 1.0.0.pre.2 and onwards use <code>/keybase/private/&lt;user&gt;/kbsecret/.config</code>\nas the configuration directory, rather than <code>~/.config/kbsecret</code>.</p>\n<p><code>/keybase/private/&lt;user&gt;/kbsecret/.config/commands.ini</code> can be used to configure individual <code>kbsecret</code> subcommands.</p>\n<p>For example, this is how you would tell <code>kbsecret</code> to always pass <code>--no-notify</code> to\n<code>kbsecret new-session</code>:</p>\n<pre><code class=\"language-ini\">[new-session]\nargs = --no-notify</code></pre>\n<p>Users can specify additional keys and values for each <code>kbsecret</code> subcommand, but only\nthe <code>args</code> key is explicitly retrieved. All others need to be handled manually by the subcommand,\nor via <code>KBSecret::Config.command</code> (see the <a href=\"http://www.rubydoc.info/gems/kbsecret/\">API docs</a>).</p>\n<h2 id=\"custom-types\">Custom types</h2>\n<p>KBSecret doesn&#39;t restrict you to the record types provided by the installation &mdash; you can\nwrite your own!</p>\n<p>Record types in KBSecret are just class definitions (with a little DSL magic), and custom\nones get loaded from <code>/keybase/private/&lt;user&gt;/kbsecret/.config/record/</code>.</p>\n<p>Here&#39;s an example of a simple, single-field record (<code>simple.rb</code>). It&#39;s just 3 lines!</p>\n<pre><code class=\"language-ruby\">class KBSecret::Record::Simple &lt; KBSecret::Record::Abstract\n  data_field :input\nend</code></pre>\n<p>Placed in the directory above, it&#39;ll work exactly as expected:</p>\n<pre><code class=\"language-bash\">$ kbsecret new simple foobar\nInput? hello, my simple record type!\n\n$ kbsecret list -t simple\nfoobar</code></pre>\n<p>Check out <code>KBSecret::Record::Abstract</code> in the <a href=\"http://www.rubydoc.info/gems/kbsecret/\">API docs</a>\nfor the full spec.</p>\n<h2 id=\"shell-completion\">Shell completion</h2>\n<p>Limited shell completion is currently available for GNU Bash. The\n<a href=\"https://github.com/kbsecret/kbsecret/blob/master/README.md\">README</a> has the details on how to\ngenerate it.</p>\n<p>KBSecret was written with shell completion in mind. Commands like <code>kbsecret list</code>,\n<code>kbsecret sessions</code>, and <code>kbsecret types</code> all provide easy-to-parse completable options,\nand all core <code>kbsecret</code> subcommands support the <code>--introspect-flags</code> flag:</p>\n<pre><code class=\"language-bash\">$ kbsecret list --introspect-flags\n-s\n--session\n-t\n--type\n-a\n--show-all\n-V\n--verbose\n-w\n--no-warn\n-h\n--help\n--introspect-flags</code></pre>\n<p>Together, these are useful primitives for building new completion scripts. If you happen to write\nsome, please consider submitting them to KBSecret!</p>\n","data":{"layout":"default"},"isEmpty":false,"excerpt":""}