add command reference

astro.config.mjs

@@ -41,6 +41,10 @@ export default defineConfig({
           label: 'Configuration',
           autogenerate: { directory: 'configuration' },
         },
+        {
+          label: 'Reference',
+          autogenerate: { directory: 'reference' },
+        },
         {
           label: 'Self hosting',
           items: [

src/content/docs/reference/gen-completions.mdx

@@ -0,0 +1,21 @@
+---
+title: gen-completions
+---
+
+[Shell completions](https://en.wikipedia.org/wiki/Command-line_completion) for Atuin can be generated by specifying the output directory and desired shell via `gen-completions` subcommand.
+
+```
+$ atuin gen-completions --shell bash --out-dir $HOME
+
+Shell completion for BASH is generated in "/home/user"
+```
+
+Possible values for the `--shell` argument are the following:
+
+- `bash`
+- `fish`
+- `zsh`
+- `powershell`
+- `elvish`
+
+Also, see the [supported shells](https://atuin.sh/docs/#supported-shells).

src/content/docs/reference/import.mdx

@@ -0,0 +1,33 @@
+---
+title: import
+---
+
+# `atuin import`
+
+Atuin can import your history from your "old" history file
+
+`atuin import auto` will attempt to figure out your shell (via \$SHELL) and run
+the correct importer
+
+Unfortunately these older files do not store as much information as Atuin does,
+so not all features are available with imported data.
+
+# zsh
+
+```
+atuin import zsh
+```
+
+If you've set HISTFILE, this should be picked up! If not, try
+
+```
+HISTFILE=/path/to/history/file atuin import zsh
+```
+
+This supports both the simple and extended format
+
+# bash
+
+```
+atuin import bash
+```

src/content/docs/reference/list.mdx

@@ -0,0 +1,33 @@
+---
+title: history list
+---
+
+# `atuin history list`
+
+
+| Arg              | Description                                                                   |
+|------------------|-------------------------------------------------------------------------------|
+| `--cwd`/`-c`     | The directory to list history for (default: all dirs)                         |
+| `--session`/`-s` | Enable listing history for the current session only (default: false)          |
+| `--human`        | Use human-readable formatting for the timestamp and duration (default: false) |
+| `--cmd-only`     | Show only the text of the command (default: false)                            |
+| `--reverse`      | Reverse the order of the output (default: false)                              |
+| `--format`       | Specify the formatting of a command (see below)                               |
+| `--print0`       | Terminate the output with a null, for better multiline support                                                                              |
+
+
+## Format
+
+Customize the output of `history list`
+
+Example
+
+```
+atuin history list --format "{time} - {duration} - {command}"
+```
+
+Supported variables
+
+```
+{command}, {directory}, {duration}, {user}, {host} and {time}
+```

src/content/docs/reference/search.md

@@ -0,0 +1,67 @@
+---
+title: search
+---
+
+Atuin search supports wildcards, with either the `*` or `%` character. By
+default, a prefix search is performed (ie, all queries are automatically
+appended with a wildcard).
+
+| Arg                  | Description                                                                   |
+| -------------------- | ----------------------------------------------------------------------------- |
+| `--cwd`/`-c`         | The directory to list history for (default: all dirs)                         |
+| `--exclude-cwd`      | Do not include commands that ran in this directory (default: none)            |
+| `--exit`/`-e`        | Filter by exit code (default: none)                                           |
+| `--exclude-exit`     | Do not include commands that exited with this value (default: none)           |
+| `--before`           | Only include commands ran before this time(default: none)                     |
+| `--after`            | Only include commands ran after this time(default: none)                      |
+| `--interactive`/`-i` | Open the interactive search UI (default: false)                               |
+| `--human`            | Use human-readable formatting for the timestamp and duration (default: false) |
+| `--limit`            | Limit the number of results (default: none)                                   |
+| `--offset`           | Offset from the start of the results (default: none)                          |
+| `--delete`           | Delete history matching this query                                            |
+| `--delete-it-all`    | Delete all shell history                                                      |
+| `--reverse`          | Reverse order of search results, oldest first                                 |
+| `--format`/`-f`      | Available variables: {command}, {directory}, {duration}, {user}, {host}, {time}, {exit} and {relativetime}. Example: --format "{time} - [{duration}] - {directory}$\t{command}" |
+| `--inline-height`    | Set the maximum number of lines Atuin's interface should take up              |
+| `--help`/`-h`        | Print help                                                                    |
+
+## `atuin search -i`
+
+Atuin's interactive search TUI allows you to fuzzy search through your history.
+
+![compact](https://user-images.githubusercontent.com/1710904/161623659-4fec047f-ea4b-471c-9581-861d2eb701a9.png)
+
+You can replay the `nth` command with `alt + #` where `#` is the line number of the command you would like to replay.
+
+Note: This is not yet supported on macOS.
+
+## Examples
+
+```
+# Open the interactive search TUI
+atuin search -i
+
+# Open the interactive search TUI preloaded with a query
+atuin search -i atuin
+
+# Search for all commands, beginning with cargo, that exited successfully
+atuin search --exit 0 cargo
+
+# Search for all commands, that failed, from the current dir, and were ran before April 1st 2021
+atuin search --exclude-exit 0 --before 01/04/2021 --cwd .
+
+# Search for all commands, beginning with cargo, that exited successfully, and were ran after yesterday at 3pm
+atuin search --exit 0 --after "yesterday 3pm" cargo
+
+# Delete all commands, beginning with cargo, that exited successfully, and were ran after yesterday at 3pm
+atuin search --delete --exit 0 --after "yesterday 3pm" cargo
+
+# Search for a command beginning with cargo, return exactly one result.
+atuin search --limit 1 cargo
+
+# Search for a single result for a command beginning with cargo, skipping (offsetting) one result
+atuin search --offset 1 --limit 1 cargo
+
+# Find the oldest cargo command
+atuin search --limit 1 --reverse cargo
+```

src/content/docs/reference/stats.mdx

@@ -0,0 +1,52 @@
+---
+title: stats
+---
+
+Atuin can also calculate stats based on your history - this is currently a
+little basic, but more features to come.
+
+## 1-day stats
+
+You provide the starting point, and Atuin computes the stats for 24h from that point.
+Date parsing is provided by `interim`, which supports different formats
+for full or relative dates. Certain formats rely on the dialect option in your
+[configuration](../../docs/config/config.md#dialect) to differentiate day from month.
+Refer to [the module's documentation](https://docs.rs/interim/0.1.0/interim/#supported-formats) for more details on the supported date formats.
+
+```
+$ atuin stats last friday
+
++---------------------+------------+
+| Statistic           | Value      |
++---------------------+------------+
+| Most used command   | git status |
++---------------------+------------+
+| Commands ran        |        450 |
++---------------------+------------+
+| Unique commands ran |        213 |
++---------------------+------------+
+
+# A few more examples:
+$ atuin stats 2018-04-01
+$ atuin stats April 1
+$ atuin stats 01/04/22
+$ atuin stats last thursday 3pm  # between last thursday 3:00pm and the following friday 3:00pm
+```
+
+## Full history stats
+
+```
+$ atuin stats
+# or
+$ atuin stats all
+
++---------------------+-------+
+| Statistic           | Value |
++---------------------+-------+
+| Most used command   |    ls |
++---------------------+-------+
+| Commands ran        |  8190 |
++---------------------+-------+
+| Unique commands ran |  2996 |
++---------------------+-------+
+```

src/content/docs/reference/sync.mdx

@@ -0,0 +1,79 @@
+---
+title: sync
+---
+
+Atuin can back up your history to a server, and use this to ensure multiple
+machines have the same shell history. This is all encrypted end-to-end, so the
+server operator can _never_ see your data!
+
+Anyone can host a server (try `atuin server start`, more docs to follow), but I
+host one at https://api.atuin.sh. This is the default server address, which can
+be changed in the [config](/docs/config/config.md#sync_address). Again, I _cannot_ see your data, and
+do not want to.
+
+## Sync frequency
+
+Syncing will happen automatically, unless configured otherwise. The sync
+frequency is configurable in [config](/docs/config/config.md#sync_frequency)
+
+## Sync
+
+You can manually trigger a sync with `atuin sync`
+
+## Register
+
+Register for a sync account with
+
+```
+atuin register -u <USERNAME> -e <EMAIL> -p <PASSWORD>
+```
+
+If you don't want to have your password be included in shell history, you can omit
+the password flag and you will be prompted to provide it through stdin.
+
+Usernames must be unique and only contain alphanumerics or hyphens,
+and emails shall only be used for important notifications (security breaches, changes to service, etc).
+
+Upon success, you are also logged in :) Syncing should happen automatically from
+here!
+
+## Delete
+
+You can delete your sync account with
+
+```
+atuin account delete
+```
+
+This will remove your account and all synchronized history from the server. Local data will not be touched!
+
+## Key
+
+As all your data is encrypted, Atuin generates a key for you. It's stored in the
+Atuin data directory (`~/.local/share/atuin` on Linux).
+
+You can also get this with
+
+```
+atuin key
+```
+
+Never share this with anyone!
+
+## Login
+
+If you want to log in to a new machine, you will require your encryption key
+(`atuin key`).
+
+```
+atuin login -u <USERNAME> -p <PASSWORD> -k <KEY>
+```
+
+If you don't want to have your password be included in shell history, you can omit
+the password flag and you will be prompted to provide it through stdin.
+
+## Logout
+
+```
+atuin logout
+```