Skip to content

README.md

Latest commit

 

History

History
187 lines (134 loc) · 5.27 KB

README.md

File metadata and controls

187 lines (134 loc) · 5.27 KB
Raw

Atuin Role

Atuin shell history synchronization with Fish shell integration and authentication.

Description

The Atuin role configures Atuin shell history synchronization, providing encrypted, searchable command history that syncs across multiple machines. It includes Fish shell integration and handles authentication with the Atuin sync server.

Requirements

  • Ubuntu 20.04 LTS or later
  • Ansible 2.12 or later
  • Common role (automatically included as dependency)
  • Fish role (automatically included as dependency)
  • CLI Tools role (automatically included as dependency for atuin binary)
  • Atuin account credentials (stored in vault)

Role Variables

Available Variables

The following variables can be set in defaults/main.yml:

# Atuin configuration
atuin_config_dir: "{{ ansible_user_dir }}/.config/atuin"
atuin_data_dir: "{{ ansible_user_dir }}/.local/share/atuin"

# Fish integration
fish_config_dir: "{{ ansible_user_dir }}/.config/fish/conf.d"
atuin_fish_config: "{{ fish_config_dir }}/atuin.fish"

# Authentication configuration (requires vault variables)
# atuin_username: "{{ vault_atuin_username }}"
# atuin_password: "{{ vault_atuin_password }}"
# atuin_email: "{{ vault_atuin_email }}"

# Sync configuration
atuin_sync_address: "https://api.atuin.sh"
atuin_auto_sync: true
atuin_sync_frequency: "10m"

# History configuration
atuin_max_history: 10000
atuin_search_mode: "fuzzy"

# User configuration
target_user: "{{ ansible_user }}"

Variable Descriptions

  • atuin_config_dir: Directory for Atuin configuration files
  • atuin_data_dir: Directory for Atuin local data storage
  • fish_config_dir: Fish shell configuration directory
  • atuin_fish_config: Path to Atuin Fish integration file
  • atuin_username: Atuin account username (vaulted)
  • atuin_password: Atuin account password (vaulted)
  • atuin_email: Atuin account email (vaulted)
  • atuin_sync_address: Atuin sync server URL
  • atuin_auto_sync: Whether to enable automatic synchronization
  • atuin_sync_frequency: How often to sync history
  • atuin_max_history: Maximum number of history entries
  • atuin_search_mode: History search mode (fuzzy, exact, etc.)
  • target_user: User for which Atuin is being configured

Dependencies

  • common: Base system setup and essential packages
  • fish: Fish shell for integration
  • cli_tools: CLI tools for atuin binary installation

Vault Variables

The following variables must be defined in your vault file (group_vars/all/vault.yml):

vault_atuin_username: "your-atuin-username"
vault_atuin_password: "your-atuin-password"
vault_atuin_email: "your-email@example.com"

Example Playbook

---
- hosts: servers
  become: yes
  roles:
    - common
    - fish
    - cli_tools
    - atuin

Features

  • Encrypted History: All command history is encrypted before sync
  • Cross-machine Sync: Access your command history from any machine
  • Fuzzy Search: Advanced search capabilities with fuzzy matching
  • Fish Integration: Seamless integration with Fish shell
  • Automatic Authentication: Handles login to Atuin sync service
  • Privacy Focused: Commands are encrypted and only you can decrypt them

Authentication Setup

To use this role, you need an Atuin account:

  1. Sign up at atuin.sh or set up your own sync server
  2. Store your credentials in the vault file:
ansible-vault edit group_vars/all/vault.yml

Add your credentials:

vault_atuin_username: "your-username"
vault_atuin_password: "your-secure-password"
vault_atuin_email: "your-email@example.com"

Fish Integration

The role configures Fish shell integration by:

  • Deploying Atuin Fish configuration
  • Setting up key bindings for history search
  • Configuring automatic history import
  • Enabling real-time sync

Usage

After installation, Atuin provides:

  • Ctrl+R: Interactive history search
  • Up Arrow: Navigate through history with context
  • Automatic Import: Existing Fish history is imported
  • Real-time Sync: New commands are synced automatically

Configuration

The role creates several configuration files:

  • ~/.config/atuin/config.toml: Main Atuin configuration
  • ~/.config/fish/conf.d/atuin.fish: Fish shell integration
  • ~/.local/share/atuin/: Local history database

Security

Atuin implements strong security measures:

  • End-to-end Encryption: History is encrypted with your key
  • Zero-knowledge: Atuin servers cannot read your history
  • Secure Authentication: Uses secure authentication protocols
  • Local First: History is stored locally and optionally synced

Privacy

  • Commands are encrypted before leaving your machine
  • Only you have the decryption key
  • Atuin servers cannot read your command history
  • You can self-host the sync server for complete control

Troubleshooting

Common issues and solutions:

  • Authentication failed: Verify credentials in vault file
  • Sync not working: Check internet connectivity and server status
  • Fish integration issues: Ensure Fish shell is properly configured
  • History not importing: Check Fish history file permissions

Self-hosting

To use a self-hosted Atuin server, modify the sync address:

atuin_sync_address: "https://your-atuin-server.com"

License

MIT

Author Information

Development Team - Internal Use