diff options
author | Ellie Huxtable <ellie@elliehuxtable.com> | 2023-06-21 09:14:55 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-06-21 09:14:55 +0100 |
commit | 395aa81c2aeb7f33c362c14c9328f3fd54c4aecc (patch) | |
tree | e0e26d722e701e1b2a070de778c71ee9b5247e89 /docs | |
parent | a75e516986ab2ba8b0997dd93271b58fa1986637 (diff) |
Revamp getting started guide (#1065)
We were lacking some docs here really. Walk new users through getting
installed and signed up!
Coming next
- Common config (how to disable the up arrow lol)
- Troubleshooting
- Community config/integrations
Diffstat (limited to 'docs')
-rw-r--r-- | docs/docs/advanced-install.md (renamed from docs/docs/index.md) | 90 | ||||
-rw-r--r-- | docs/docs/guide/index.md | 156 | ||||
-rw-r--r-- | docs/docusaurus.config.js | 2 | ||||
-rw-r--r-- | docs/src/pages/index.js | 2 |
4 files changed, 169 insertions, 81 deletions
diff --git a/docs/docs/index.md b/docs/docs/advanced-install.md index 19f92eaa3..f9ff719f6 100644 --- a/docs/docs/index.md +++ b/docs/docs/advanced-install.md @@ -1,85 +1,16 @@ --- -title: Getting Started -sidebar_position: 1 +title: Advanced Install --- +Generally, we recommend using our install script. It ensures you use the most +up-to-date Atuin, and that your shell plugin is correctly setup. It will prefer +the system package manager wherever necessary! -Atuin replaces your existing shell history with a SQLite database, and records -additional context for your commands. Additionally, it provides optional and -_fully encrypted_ synchronisation of your history between machines, via an Atuin -server. +However, I totally understand if you'd rather do things yourself and not run a +script from the internet. If so, follow on! -You may use either the server I host, or host your own! Or just don't use sync -at all. As all history sync is encrypted, I couldn't access your data even if -I wanted to. And I **really** don't want to. +## Install Atuin -## Supported Shells - -- zsh -- bash -- fish -- nushell - -## Community - -Atuin has a community Discord, available [here](https://discord.gg/Fq8bJSKPHh) - -# Quickstart - -## With the default sync server - -This will sign you up for the default sync server, hosted by me. Everything is end-to-end encrypted, so your secrets are safe! - -Read more below for offline-only usage, or for hosting your own server. - -``` -bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh) - -atuin register -u <USERNAME> -e <EMAIL> -p <PASSWORD> -atuin import auto -atuin sync -``` - -Then restart your shell! - -### Opt-in to activity graph -Alongside the hosted Atuin server, there is also a service which generates activity graphs for your shell history! These are inspired by the GitHub graph. - -For example, here is mine: - -![Activity Graph Example](/img/activity-graph-example.png) - -If you wish to get your own, after signing up for the sync server, run this - -``` -curl https://api.atuin.sh/enable -d $(cat ~/.local/share/atuin/session) -``` - -The response includes the URL to your graph. Feel free to share and/or embed this URL, the token is _not_ a secret, and simply prevents user enumeration. - -## Offline only (no sync) - -``` -bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh) - -atuin import auto -``` - -Then restart your shell! - -## Install - -### Script (recommended) - -The install script will help you through the setup, ensuring your shell is -properly configured. It will also use one of the below methods, preferring the -system package manager where possible (pacman, homebrew, etc etc). - -``` -# do not run this as root, root will be asked for if required -bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh) -``` - -And then follow [the shell setup](#shell-plugin) +Atuin is in a number of package repositories! Please choose whichever works best for you. ### With cargo @@ -147,13 +78,14 @@ And then follow [the shell setup](#shell-plugin) ### From source +Note: Atuin builds on the latest stable version of Rust, and we make no +promises regarding older versions. We recommend using rustup. + ``` git clone https://github.com/ellie/atuin.git cd atuin/atuin cargo install --path . ``` - -And then follow [the shell setup](#shell-plugin) ## Shell plugin diff --git a/docs/docs/guide/index.md b/docs/docs/guide/index.md new file mode 100644 index 000000000..f605f520a --- /dev/null +++ b/docs/docs/guide/index.md @@ -0,0 +1,156 @@ +--- +title: Getting Started +id: index +sidebar_position: 1 +--- + +Atuin replaces your existing shell history with a SQLite database, and records +additional context for your commands. With this context, Atuin gives you faster +and better search of your shell history! + +Additionally, Atuin (optionally) syncs your shell history between all of your +machines! Fully end-to-end encrypted, of course. + +You may use either the server I host, or host your own! Or just don't use sync +at all. As all history sync is encrypted, I couldn't access your data even if I +wanted to. And I **really** don't want to. + +If you have any problems, please open an [issue](https://github.com/ellie/atuin/issues) or get in touch on our [Discord](https://discord.gg/Fq8bJSKPHh)! + +## Supported Shells + +- zsh +- bash +- fish +- nushell + +# Quickstart + +Please do try and read this guide, but if you're in a hurry and want to get started quickly: + +``` +bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh) + +atuin register -u <USERNAME> -e <EMAIL> +atuin import auto +atuin sync +``` + +# Full Guide + +Let's get started! First up, you will want to install Atuin. We have an install +script which handles most of the commonly used platforms and package managers: + +``` +bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh) +``` + +The script will install the binary and attempt to configure your shell. Atuin +uses a shell plugin to ensure that we capture new shell history. But for older +history, you will need to import it + +This will import the history for your current shell: +``` +atuin import auto +``` + +Alternatively, you can specify the shell like so: + +``` +atuin import bash +atuin import zsh # etc +``` + +## Register + +At this point, you have Atuin storing and searching your shell history! But it +isn't syncing it just yet. To do so, you'll need to register with the sync +server. All of your history is fully end-to-end encrypted, so there are no +risks of the server snooping on you. + +Note: if you already have an account and wish to sync with an additional +machine, follow the [below guide](#syncing-additional-machines) instead. + +``` +atuin register -u <YOUR_USERNAME> -e <YOUR EMAIL> +``` + +After registration, Atuin will generate an encryption key for you and store it +locally. This is needed for logging in to other machines, and can be seen with + +``` +atuin key +``` + +Please **never** share this key with anyone! The Atuin developers will never +ask you for your key, your password, or the contents of your Atuin directory. + +If you lose your key, we can do nothing to help you. We recommend you store +this somewhere safe, such as in a password manager. + +## First sync +By default, Atuin will sync your history once per hour. This can be +[configured](/docs/config#sync_frequency). + +To run a sync manually, please run + +``` +atuin sync +``` + +Atuin tries to be smart with a sync, and not waste data transfer. However, if +you are seeing some missing data, please try running + +``` +atuin sync -f +``` + +This triggers a full sync, which may take longer as it works through historical data. + +## Syncing additional machines + +When only signed in on one machine, Atuin sync operates as a backup. This is +pretty useful by itself, but syncing multiple machines is where the magic +happens. + +First, ensure you are [registered with the sync server](#register) and make a +note of your key. You can see this with `atuin key`. + +Then, install Atuin on a new machine. Once installed, login with + +``` +atuin login -u <USERNAME> +``` + +You will be prompted for your password, and for your key. + +Syncing will happen automatically in the background, but you may wish to run it manually with + +``` +atuin sync +``` + +Or, if you see missing data, force a full sync with: + +``` +atuin sync -f +``` + +## Opt-in to activity graph +Alongside the hosted Atuin server, there is also a service which generates +activity graphs for your shell history! These are inspired by the GitHub graph. + +For example, here is mine: + +![Activity Graph Example](https://api.atuin.sh/img/ellie.png?token=0722830c382b42777bdb652da5b71efb61d8d387) + +If you wish to get your own, after signing up for the sync server, run this + +``` +curl https://api.atuin.sh/enable -d $(cat ~/.local/share/atuin/session) +``` + +The response includes the URL to your graph. Feel free to share and/or embed +this URL, the token is _not_ a secret, and simply prevents user enumeration. + + diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index ad70c0019..c087971c2 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -70,7 +70,7 @@ const config = { items: [ { type: 'doc', - docId: 'index', + docId: 'guide/index', position: 'left', label: 'Docs', }, diff --git a/docs/src/pages/index.js b/docs/src/pages/index.js index cd9837591..de42742b4 100644 --- a/docs/src/pages/index.js +++ b/docs/src/pages/index.js @@ -20,7 +20,7 @@ function HomepageHeader() { <div className={styles.buttons}> <Link className="button button--primary button--lg" - to="/docs"> + to="/docs/guide"> Get Started </Link> </div> |