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
This commit is contained in:
Ellie Huxtable
GitHub
parent
a75e516986
commit
395aa81c2a
5 changed files with 169 additions and 82 deletions
|
|
@ -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:
|
||||
|
||||
|
||||
|
||||
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,14 +78,15 @@ 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
|
||||
|
||||
Once the binary is installed, the shell plugin requires installing. If you use
|
||||
156
docs/docs/guide/index.md
Normal file
156
docs/docs/guide/index.md
Normal file
|
|
@ -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:
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
|
@ -70,7 +70,7 @@ const config = {
|
|||
items: [
|
||||
{
|
||||
type: 'doc',
|
||||
docId: 'index',
|
||||
docId: 'guide/index',
|
||||
position: 'left',
|
||||
label: 'Docs',
|
||||
},
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
Loading…
Reference in a new issue