<template>
  <div>
    <div class="title">
      <h1><span class="code">dotty</span> tool reference</h1>   
      <p>Usage reference for the official Dotty CLI application: <span class="code">dotty</span></p>
    </div>

    <p><span class="code">dotty</span> is designed to be an easy-to-use wrapper around the Dotty <router-link :to="{name: 'DocumentationRest'}">REST API</router-link>, and we recommend most people use this tool when interacting with Dotty.</p>
    <p>If you are new to Dotty, then we recommend reading the <router-link :to="{name: 'DocumentationQuickStart'}">quick-start guide</router-link> first.</p>
    <div class="alert alert-info">
      By using the Dotty client or API you agree to Dotty's <a href="/privacy" target="_blank">Privacy Policy</a> and <a href="/terms" target="_blank">Terms of Use</a>.
    </div>

    <h3>Installation</h3>
    <p>Please refer to the <router-link :to="{name: 'DocumentationQuickStart'}">quick-start guide</router-link> for help with installation.</p>

    <h3>Issuing commands</h3>
    <p>The <span class="code">dotty</span> tool always accepts a command as its first argument.</p>
    <p>After parsing the command, the tool will check any flags you've included, which must come <strong>after</strong> the command.</p>
    <p>For example:</p>
    <div class="code-block">
      dotty -k nginx push
    </div>
    <p>is invalid. It should instead be written:</p>
    <div class="code-block">
      dotty push -k nginx
    </div>
    <p>or</p>
    <div class="code-block">
      dotty push -k=nginx
    </div>
    <p>In this example, <span class="code">push</span> is the command, <span class="code">-k</span> is the flag, and <span class="code">nginx</span> is the setting for the flag. Note that not all flags necessarily have settings.</p>

    <h3>Aliasing <span class="code">dotty</span></h3>
    <p>For convenience, you may want to alias the <span class="code">dotty</span> tool.</p>
    <p>For example, you may want to run commands using a shortened version (such as <span class="code">dt</span> or <span class="code">dtt</span> - as seen on the homepage). In addition, you may want to alias specific Dotty commands.</p>
    <p>Below are some example alias declarations you can add to your shell:</p>
    <ul>
      <li><span class="code">alias dtt='dotty'</span></li>
      <li><span class="code">alias dtta='dotty add'</span></li>
    </ul>

    <h3><span class="code">dotty</span> commands</h3>
    <p>This section lists the commands available when using the <span class="code">dotty</span> CLI.</p>

    <h4><span class="code">dotty register</span></h4>
    <p>Registers a new account with Dotty and logs-in to the new account.</p>
    <p>The command will request an email address and a password.</p>
    <p>Registration is successful if no error messages occurred.</p>
    <p>The command updates the <span class="code">dotty</span> local configuration with an <span class="code">accessToken</span> upon success.</p>
  <p>If a <span class="code">accessToken</span> exists already in the local configuration, then this will be overwritten with the new key. As such, each instance of <span class="code">dotty</span> can only be associated with one account. The rest of the local configuration will not be updated.</p>


    <h4><span class="code">dotty login</span></h4>
    <p>Login to an existing Dotty account.</p>
    <p>The command will request an email address and a password.</p>
    <p>Login is successful if no error messages occurred.</p>
    <p>The command updates the <span class="code">dotty</span> local configuration with an <span class="code">accessToken</span> upon success.</p>
    <p>If a <span class="code">accessToken</span> exists already in the local configuration, then this will be overwritten with the new key. As such, each instance of <span class="code">dotty</span> can only be associated with one account. The rest of the local configuration will not be updated.</p>

    <h4><span class="code">dotty logout</span></h4>
    <p>Logout from the Dotty account.</p>
    <p>This command has different functionality depending on the flags passed.</p>
    <p>The default behaviour is to remove and invalidate the access token being used to make the request.</p>
    <h5>Flags</h5>
    <ul>
      <li><span class="code">-o</span>: (optional exclusive) invalidate all access tokens <em>other</em> than the current one.</li>
      <li><span class="code">-a</span>: (optional exclusive) invalidate <em>all</em> access tokens.</li>
    </ul>

    <h4><span class="code">dotty reset-password</span></h4>
    <p>Requests a password-reset email to be sent to the account-holder.</p>
    <p>The command will prompt for an email address and, if the address is found to be associated with a Dotty account, an email will be sent to the address with a token that can be used with <span class="code">dotty change-password -t</span>.</p>

    <h4><span class="code">dotty change-password</span></h4>
    <p>Changes the password for the specified account.</p>
    <p>The command will prompt for the current password and a new password, which will become the new account password upon success.</p>
    <p>The command can also be used to complete the "reset password" process initiated with <span class="code">dotty reset-password</span>, as described in the <em>Flags</em> section below.</p>
    <h5>Flags</h5>
    <ul>
      <li><span class="code">-t</span>: (optional) indicate that you have a token to use instead of the current password in order to supply a new password. Dotty will request this token instead of a current password.</li>
    </ul>

    <h4><span class="code">dotty add</span></h4>
    <p>Adds a new config or dotfile to the logged-in Dotty account.</p>
    <p>The command does the following:</p>
    <ul>
      <li>Adds the specified key and path to the local configuration</li>
      <li>Implicitly 'pushes' the new config to the Dotty cloud using the specified path as the default path</li>
    </ul>
    <p>The command will fail if a config with the specified key already exists for this account (either in the local configuration or in the Dotty cloud).</p>
    <h5>Flags</h5>
    <ul>
      <li><span class="code">-k</span>: (required) the key to associate with this dotfile. Must be unique within the account.</li>
      <li><span class="code">-f</span>: (required) the path to read the file from.</li>
    </ul>
    <h5>Example</h5>
    <div class="code-block">
      dotty add -k vimrc -f ~/.vimrc
    </div>

    <h4><span class="code">dotty push</span></h4>
    <p>Pushes a previously <span class="code">add</span>ed config to the Dotty cloud.</p>
    <p>The command resolves the path to read the file from by using the local configuration. Therefore, the command fails if there is no local configuration for the file.</p>
    <p>The command will fail if the dotfile has not yet been <span class="code">add</span>ed.</p>
    <h5>Flags</h5>
    <ul>
      <li><span class="code">-k</span>: (required) the key of the dotfile to push.</li>
    </ul>
    <h5>Example</h5>
    <div class="code-block">
      dotty push -k vimrc
    </div>

    <h4><span class="code">dotty pull</span></h4>
    <p>Pulls the latest version of a previously <span class="code">add</span>ed config/dotfile and writes it locally.</p>
    <p>If there is no local configuration yet for the specified key, the command will initially prompt for a local path before writing, and update the local configuration accordingly.</p>
    <p>This command will fail if the file's key has not yet been <span class="code">add</span>ed.</p>
    <p>This command will create all necessary directories in order to write the file with permissions <span class="code">0777</span>.</p>
    <p>If the command results in a new file being written, it will be given permissions <span class="code">0644</span>.</p>
    <p>This command may need to be run as root/administrator in cases where the user does not have write-access to the file's local path.</p>
    <h5>Flags</h5>
    <ul>
      <li><span class="code">-k</span>: (required) the key of the file to pull.</li>
    </ul>
    <h5>Examples</h5>
    <p>Standard case:</p>
    <div class="code-block">
      dotty pull -k vimrc
    </div>

    <h4><span class="code">dotty ls</span></h4>
    <p>List the configs/dotfiles that have been <span class="code">add</span>ed to the account.</p>
    <p>The command will also output the default path and any local paths of the specified key.</p>
    <h5>Example</h5>
    <div class="code-block">
      dotty ls
    </div>

    <h4><span class="code">dotty update</span></h4>
    <p>Update the local configuration by inserting any missing configs/dotfiles associated with this account in the Dotty cloud.</p>
    <p>This command does not write to any files other than <span class="code">dotty</span>'s own configuration.</p>
    <p>For each locally-unknown key returned by the request, this command will prompt for a local path.</p>
    <h5>Example</h5>
    <div class="code-block">
      dotty update
    </div>

    <h4><span class="code">dotty rm</span></h4>
    <p>Remove the specified key from the local configuration and from the Dotty cloud.</p>
    <p>This command does not delete or write to the actual dotfile/config itself. It only removes the reference from Dotty.</p>
    <p>Currently, this command is useful for if you want to re-add a dotfile with a different default path.</p>
    <h5>Flags</h5>
    <ul>
      <li><span class="code">-k</span>: (required) the key of the file to be removed.</li>
    </ul>
    <h5>Example</h5>
    <div class="code-block">
      dotty rm -k vimrc
    </div>

    <h3>Local Dotty configuration</h3>
    <p><span class="code">dotty</span> maintains its local configuration on each machine using its own dotfile, <span class="code">~/.dotty.json</span>.</p>
    <p>This file is safe to edit by hand, if you prefer this to using the commands provided by the <span class="code">dotty</span> tool itself. However, if you write invalid JSON then the tool will break.</p>
    <p>The file itself is very simple, with a typical structure:</p>
    <pre class="code-block">
      {
        "accessToken": "xxx.yyy.zzz",
        "configs": [
          {
            "key": "vimrc",
            "path": "/Users/jane/.vimrc"
          },
          {
            "key": "tmux",
            "path": "/Users/jane/.tmux.conf"
          },
          {
            "key": "nginx",
            "path": "/etc/nginx/nginx.conf"
          }
        ]
      }
    </pre>
    <p>The <span class="code">accessToken</span> field spcifies the token which authorises <span class="code">dotty</span> against your Dotty account in the cloud when making authenticated requests.</p>
    <p>The <span class="code">configs</span> array lists all files in the local configuration, along with the key and the path to the file locally.</p>
    <div class="alert alert-warning">We strongly recommend that you don't add <span class="code">~/.dotty.json</span> to Dotty as this may introduce race problems and removes the point in having a local configuration.</div>


  </div>
</template>

<script>
export default {
  name: 'documentationClient',
  data() {
    return {
    };
  },
};

</script>

<style scoped lang="scss">

</style>
