diff --git a/docs/docs/index.md b/docs/docs/advanced-install.md similarity index 53% rename from docs/docs/index.md rename to docs/docs/advanced-install.md index 19f92eaa..f9ff719f 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 -e -p -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 00000000..f605f520 --- /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 -e +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 -e +``` + +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 +``` + +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 ad70c001..c087971c 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 cd983759..de42742b 100644 --- a/docs/src/pages/index.js +++ b/docs/src/pages/index.js @@ -20,7 +20,7 @@ function HomepageHeader() {
+ to="/docs/guide"> Get Started
diff --git a/install.sh b/install.sh index ef8b9200..0d306464 100755 --- a/install.sh +++ b/install.sh @@ -105,7 +105,6 @@ __atuin_install_mac(){ if command -v brew &> /dev/null then echo "Installing with brew" - brew tap ellie/atuin brew install atuin else echo "Could not find brew, installing with Cargo"