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:
parent
a75e516986
commit
395aa81c2a
5 changed files with 169 additions and 82 deletions
|
@ -1,85 +1,16 @@
|
||||||
---
|
---
|
||||||
title: Getting Started
|
title: Advanced Install
|
||||||
sidebar_position: 1
|
|
||||||
---
|
---
|
||||||
|
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
|
However, I totally understand if you'd rather do things yourself and not run a
|
||||||
additional context for your commands. Additionally, it provides optional and
|
script from the internet. If so, follow on!
|
||||||
_fully encrypted_ synchronisation of your history between machines, via an Atuin
|
|
||||||
server.
|
|
||||||
|
|
||||||
You may use either the server I host, or host your own! Or just don't use sync
|
## Install Atuin
|
||||||
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.
|
|
||||||
|
|
||||||
## Supported Shells
|
Atuin is in a number of package repositories! Please choose whichever works best for you.
|
||||||
|
|
||||||
- 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)
|
|
||||||
|
|
||||||
### With cargo
|
### With cargo
|
||||||
|
|
||||||
|
@ -147,13 +78,14 @@ And then follow [the shell setup](#shell-plugin)
|
||||||
|
|
||||||
### From source
|
### 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
|
git clone https://github.com/ellie/atuin.git
|
||||||
cd atuin/atuin
|
cd atuin/atuin
|
||||||
cargo install --path .
|
cargo install --path .
|
||||||
```
|
```
|
||||||
|
|
||||||
And then follow [the shell setup](#shell-plugin)
|
|
||||||
|
|
||||||
## Shell plugin
|
## Shell plugin
|
||||||
|
|
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:
|
||||||
|
|
||||||
|
![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.
|
||||||
|
|
||||||
|
|
|
@ -70,7 +70,7 @@ const config = {
|
||||||
items: [
|
items: [
|
||||||
{
|
{
|
||||||
type: 'doc',
|
type: 'doc',
|
||||||
docId: 'index',
|
docId: 'guide/index',
|
||||||
position: 'left',
|
position: 'left',
|
||||||
label: 'Docs',
|
label: 'Docs',
|
||||||
},
|
},
|
||||||
|
|
|
@ -20,7 +20,7 @@ function HomepageHeader() {
|
||||||
<div className={styles.buttons}>
|
<div className={styles.buttons}>
|
||||||
<Link
|
<Link
|
||||||
className="button button--primary button--lg"
|
className="button button--primary button--lg"
|
||||||
to="/docs">
|
to="/docs/guide">
|
||||||
Get Started
|
Get Started
|
||||||
</Link>
|
</Link>
|
||||||
</div>
|
</div>
|
||||||
|
|
|
@ -105,7 +105,6 @@ __atuin_install_mac(){
|
||||||
if command -v brew &> /dev/null
|
if command -v brew &> /dev/null
|
||||||
then
|
then
|
||||||
echo "Installing with brew"
|
echo "Installing with brew"
|
||||||
brew tap ellie/atuin
|
|
||||||
brew install atuin
|
brew install atuin
|
||||||
else
|
else
|
||||||
echo "Could not find brew, installing with Cargo"
|
echo "Could not find brew, installing with Cargo"
|
||||||
|
|
Loading…
Reference in a new issue