Atuin 配置管理实战指南atuin config命令与 config.toml 完整参数解析【免费下载链接】atuin✨ Making your shell magical项目地址: https://gitcode.com/gh_mirrors/at/atuin本篇技术指南以 Atuin 的atuin config子命令为主线完整讲解如何在不打开编辑器的情况下读取、修改与检查 Atuin 的配置项并结合仓库源码解析 Atuin 配置的解析顺序默认值 →config.toml→ 环境变量覆盖、类型检测机制与底层实现原理。读完本文你将掌握atuin config get/set/print的完整用法并能够对照 config.toml 中从搜索模式、过滤模式到 daemon、logs、theme、ui 等全部配置参数进行精准调优。配置从哪来三层解析来源Atuin 的配置解析集中在 crates/atuin-client/src/settings.rs 的Settings::build_config()与builder_with_data_dir()中。配置值按以下优先级合并后者覆盖前者内置默认值builder_with_data_dir()中通过set_default(...)注册的所有默认项例如search_mode fuzzy、sync_frequency 5m、style compact、enter_accept false等配置文件~/.config/atuin/config.toml可用ATUIN_CONFIG_DIR环境变量覆盖目录最终文件固定为config.toml。若文件不存在Atuin 会自动将 crates/atuin-client/config.toml 这一内置示例配置写入磁盘环境变量覆盖所有以ATUIN_为前缀的环境变量使用__作为层级分隔符Environment::with_prefix(atuin).prefix_separator(_).separator(__)例如ATUIN_SEARCH_MODE对应顶层search_modeATUIN_DAEMON__ENABLED对应daemon.enabled。atuin config命令存在的意义正是让你能够直观地看到这三层来源各自设了什么、最终生效值是什么并在 config.toml 中安全地写入新值。其实现位于 crates/atuin/src/command/client/config.rs由Get、Set、Print三个子命令构成。atuin config get key读取配置值get读取 config.toml 中指定键的原始值。键支持点号路径如daemon.enabled也可以直接读取整个表如daemon$ atuin config get search_mode fuzzy $ atuin config get daemon [daemon] enabled true socket_path /tmp/atuin_daemon.sock若键在配置文件中不存在输出占位提示$ atuin config get enter_accept (not set in config file)需要注意的是get默认只读config.toml 文件本身并不包含默认值与环境变量。结合源码GetCmd::print_current_value可以看到它通过toml_edit将配置文件解析为文档后用get_deep_key按点号逐层下钻表类型[daemon]会被整体dump_table打印标量类型则输出其字符串值。--resolved/-r查看合并后的生效值要查看三层来源合并后的最终生效值使用-r标志。它调用Settings::get_config_value(key)重建完整配置默认值 文件 环境变量并输出真正的运行时值$ atuin config get enter_accept --resolved false对于表键--resolved会把所有子项展开为扁平的key value形式键按字母序排序$ atuin config get logs --resolved logs.ai.file ai.log logs.daemon.file daemon.log logs.dir /home/user/.local/share/atuin/logs logs.enabled true logs.level info logs.search.file search.log这里能看到路径类配置如logs.dir已被shellexpand展开为绝对路径——这正是解析后与文件原文的差异所在。get_config_value还对daemon.socket_path做了特殊处理当该键未显式配置时会把 settings/daemon.rs 中Daemon::socket_path()动态计算出的默认路径$TMPDIR/atuin-$UID/atuin.sock手动插入结果方便排查 socket 问题。--verbose/-v文件值与生效值对照-v同时展示两侧适合调试为什么我配置没生效$ atuin config get enter_accept --verbose Config file: (not set in config file) Resolved: false--verbose与--resolved互斥使用前者内部同时调用print_current_value读文件与print_effective_value合并解析。atuin config set key value写入配置set直接把值写入config.toml并且保留文件原有的格式与注释。这是它的核心卖点——基于toml_edit的DocumentMut原地修改而不是重新序列化整个文件。$ atuin config set search_mode fuzzy $ atuin config set daemon.enabled true点号键会自动导航并创建中间表atuin config set keys.scroll_exits false在[keys]表不存在时会自动新建。config.rs中的测试set_adds_a_missing_key_without_touching_existing_content验证了追加新键不破坏既有注释、set_preserves_formatting_when_overwriting验证了覆盖已有键时连值后面的行尾注释如frequency 5m # sync interval都能原样保留。类型自动检测set默认--type auto遵循两条规则键已存在匹配 config.toml 中已有值的 TOML 类型detect_existing_type避免把字符串300意外变成整数300键不存在根据输入值自动推断类型值推断类型true/falseboolean42、-1integer3.14float其他string自动推断实现在parse_value的ValueType::Auto分支先匹配布尔再尝试i64再尝试f64兜底为字符串。--type/-t显式指定类型--type的优先级最高用于强制存储为指定类型可选值auto、string、boolean、integer、float。$ atuin config set sync_frequency 600 --type string限制与报错!!! warning 仅支持标量值atuin config set只能设置标量scalar配置项表与数组如history_filter、search.filters、extra_headers必须手动编辑 config.toml。试图用标量覆盖表时会得到明确指引set_deep_key中的守卫逻辑$ atuin config set logs true Error: logs is a table; use a dotted key like logs.key to set a value within it写入前set会调用Settings::validate_str对修改后的完整文档做反序列化校验——如果新值会让整个配置失效例如search_mode invalid写入会被拒绝并回滚错误信息会包含出问题的键与值避免把配置文件写坏。atuin config print [key]整体输出print以 TOML 格式输出配置内容。不带 key 时打印整个文件带 key 时只打印该节$ atuin config print daemon [daemon] enabled true socket_path /tmp/atuin_daemon.sock pidfile_path /tmp/atuin_daemon.pid autostart falseprint与get的区别print忠实反映文件结构含表头、子表嵌套适合把整个配置归档或粘贴给他人get更侧重单值查询。核心配置参数速查atuin config get/set操作的对象就是 docs/docs/configuration/config.md 中定义的整套参数。以下按功能域梳理高频参数默认值均取自builder_with_data_dir与示例配置 crates/atuin-client/config.toml。基础路径与同步参数默认值说明db_path~/.local/share/atuin/history.dbSQLite 历史数据库路径key_path~/.local/share/atuin/key加密密钥路径dialectus影响 stats 命令解析日期的格式us/ukauto_synctrue登录状态下是否自动同步update_checktrue是否每小时至多一次向https://api.atuin.sh检查更新。关闭且未配置同步时Atuin 自身不发起任何网络请求sync_addresshttps://api.atuin.sh同步服务器地址sync_frequency5m自动同步间隔支持10s/20m/1h/1d裸数字按秒解析向后兼容0表示每条命令后都同步network_timeout30s单次网络请求最大等待时间network_connect_timeout5s建立连接的最大等待时间local_timeout2s获取本地 SQLite 连接的超时extra_headers{}附加到每次同步请求的 HTTP 头适用于 Cloudflare Access 等网关场景。Atuin 自身设置的头如Authorization优先不可覆盖配置后拒绝跨源重定向避免凭据外泄搜索与过滤参数默认值说明search_modefuzzy搜索模式prefixquery*、fulltext*query*、fuzzy、daemon-fuzzy。daemon-fuzzy自 Atuin 18.13 起提供使用 daemon 内存索引需启用 daemon[daemon] enabled true, autostart true在命令行非交互搜索中它表现得与fuzzy一致filter_modeglobal交互搜索的初始过滤模式global/host/session/directory/workspace/session-preloadTUI 内可随时用 ctrl-r 轮换。各模式的搜索范围见 advanced-usagesearch_mode_shell_up_key_bindingfuzzy从 shell 上方向键绑定进入搜索时使用的搜索模式未设置时回落到search_modefilter_mode_shell_up_key_bindingglobal同上针对过滤模式inline_height_shell_up_key_binding同inline_height上方向键唤起时界面最大行数workspacesfalse在 git 仓库中自动激活workspace过滤search.filters全部模式交互搜索可用过滤模式列表即 ctrl-r 轮换顺序。filter_mode不在列表中时取第一个可用模式workspace在非 git 目录或workspaces false时自动跳过search.shellsautoAtuin ≥ 18.18按 shell 过滤搜索结果all显示全部auto显示当前 shell 及无 shell 记录的旧命令经ATUIN_SHELL环境变量识别当前 shell数组如[bash,zsh]则只显示列出的 shell表示包含无 shell 记录的命令search.frequency_score_multiplier1.0daemon-fuzzy模式下频率得分的乘数1降低、1放大、0关闭该维度search.recency_score_multiplier1.0同上针对新鲜度得分search.frecency_score_multiplier1.0最终 frecency 得分的乘数0表示完全依赖模糊匹配得分。frecency 计算式Recency Score * Recency Multiplier Frequency Score * Frequency Multiplierfuzzy模式采用 fzf 搜索语法daemon-fuzzy不支持其中的|或运算符Token匹配类型说明sbtrktfuzzy-match模糊匹配sbtrktwildexact-match (quoted)必须包含wild^musicprefix-exact-match以music开头.mp3$suffix-exact-match以.mp3结尾!fireinverse-exact-match不包含fire!^musicinverse-prefix-exact-match不以music开头!.mp3$inverse-suffix-exact-match不以.mp3结尾例如^core go$ | rb$ | py$匹配以core开头、以go、rb或py结尾的命令。TUI 外观与交互参数默认值说明stylecompactauto/full/compactauto在终端过矮时自动从full切到compactinvertfalse把搜索栏放到顶部inline_height40界面最大行数0表示全屏show_previewtrue是否预览选中命令命令超宽截断时有用max_preview_height4预览最大高度show_helptrue帮助行版本、更新提示、键位提示、历史总量show_tabstrue显示 search/inspect 标签页show_numeric_shortcutstrue列表项旁的数字快捷键1..9auto_hide_height8可用高度低于该行数时自动隐藏多余 UI 行仅在compact风格下生效0关闭exit_modereturn-originalEsc 的行为return-original恢复搜索前命令行return-query保留已输入的查询。ctrlc / ctrld 始终恢复原值keymap_modeemacs初始键位模式emacs/vim-normal/vim-insert/autoauto按触发搜索的 shell 键位决定Nushell 目前不支持恒为emacskeymap_cursor空字典各键位模式下的光标样式如{ emacs blink-block, vim_insert blink-block, vim_normal steady-block }取值default或{blink,steady}-{block,underline,bar}prefers_reduced_motionfalse减少 TUI 动画如动态刷新时间戳亦可设环境变量NO_MOTIONctrl_n_shortcutsfalsemacOS 场景用 ctrl0..9 替代 alt0..9 数字快捷键避免 option 键重映射影响输入command_chainingfalse在/||后启用命令链式补全而非替换当前行enter_acceptfalse新装用户为true为true时回车直接执行命令、tab 退回编辑。默认配置文件里写的是true源码中set_default(enter_accept, false)与文件默认值的不一致是有意为之不改变老用户肌肉记忆同时给新用户默认启用历史记录控制参数默认值说明history_filter空正则数组匹配的命令不写入历史未锚定则匹配命令任意位置。配合 prune 可清理已入库的旧记录cwd_filter空正则数组在这些目录下执行的命令不写入历史store_failedtrue是否保存非零退出码的命令secrets_filtertrue命中内置凭据正则的命令拒绝入库。覆盖 AWSAccess Key ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN、AzureAZURE_*_KEY、Google CloudGOOGLE_SERVICE_ACCOUNT_KEY、GitHub新旧 PAT、OAuth/App token、refresh token、GitLab PAT、SlackOAuth v2 bot/user、webhook、Stripe live/test key、Netlify、npm、Pulumi以及把密码和密钥当参数传入的atuin login。精确表达式见 crates/atuin-common/src/secrets.rshistory_format{time}\t{command}\t{duration}history list默认格式可用--format按次覆盖关于secrets_filter需要特别说明它同时作用于捕获的命令输出。命令文本本身干净但输出可能泄露凭据如cat .env、gh auth token因此捕获输出中识别到的凭据值会在存储前替换为****——只替换值保留变量名或 flag。正如 excluding-commands 所强调这是安全网而非保证它只识别已知格式其余敏感内容请用history_filter兜底。统计、点文件与键位参数默认值说明[stats] common_subcommandsapt/cargo/git/kubectl/npm/...这些命令的子命令计入统计如kubectl get而非仅kubectl[stats] common_prefix[sudo]统计时完全剥离的前缀源码默认还含doas[dotfiles] enabledfalse跨主机同步 shell 别名。启用后可用atuin dotfiles alias set k kubectl、atuin dotfiles alias list、atuin dotfiles alias delete k管理改后需重启 shell 或 source init 文件[keys] scroll_exitstrue滚动越过首/末条目时是否退出 TUI[keys] prefixa前缀模式前缀键如默认 ctrla 再按 d 删除选中项。完整默认前缀快捷键见 key-binding自定义见 advanced-key-binding[keys] exit_past_line_starttrue光标在行首继续左滚时退出[keys] accept_past_line_endtrue右方向键等同 tab把选中行复制到命令行待编辑[keys] accept_past_line_startfalse左方向键等同 tab[keys] accept_with_backspacefalse退格键等同 tab[preview] strategyauto预览高度计算策略auto按选中命令长度、static按当前结果集最长命令、fixed固定用max_preview_height。都受max_preview_height约束tmux 弹出窗在 tmux 内以浮层 popup 打开搜索 UI需 tmux ≥ 3.2支持 zsh/bash/fishiTerm2 原生 tmux 集成tmux -CC无法显示 popup应保持禁用。配置由atuin init读取并通过环境变量传给 shell 插件因此修改后必须重启 shell单会话禁用可设ATUIN_TMUX_POPUPfalse。任何无法使用 popup 的场景tmux 外、版本过旧、shell 不支持都会无错误回退到普通渲染。[tmux] enabled true width 80% # 或绝对列数 height 60% # 或绝对行数daemon 与日志参数默认值说明[daemon] enabledfalse启用后台守护进程历史钩子经 daemon 路由[daemon] autostartfalse按需自动启动并管理 daemon与systemd_socket true不兼容[daemon] sync_frequency5mdaemon 的同步间隔[daemon] socket_path$TMPDIR/atuin-$UID/atuin.sock客户端与 daemon 通信的 Unix socket 路径systemd_socket true时默认改为$XDG_RUNTIME_DIR/atuin.sock。未手动配置时Atuin 还会兼容探测旧版本可能遗留的$XDG_RUNTIME_DIR、$XDG_DATA_HOME路径下的旧 socket[daemon] pidfile_path~/.local/share/atuin/atuin-daemon.pid进程协调 pidfile[daemon] systemd_socketfalse使用 systemd socket activation 传入的 socket[daemon] tcp_port8889非 Unix 系统上客户端与 daemon 通信的 TCP 端口[logs] enabledtrue文件日志总开关[logs] dir~/.atuin/logs日志目录[logs] levelinfotrace/debug/info/warn/error[logs] retention4d按类型保留时长裸数字按天[logs.ai/.daemon/.search]—各日志子类型独立覆盖enabled/file/level/retention如[logs.search] file search.logtheme 与 ui参数默认值说明[theme] namedefault内置主题default/autumn/marine或~/.config/atuin/themes/可用ATUIN_THEME_DIR覆盖下的NAME.toml主题[theme] debugfalse输出主题加载失败原因可能把主题文件内容原样打到终端[theme] max_depth10主题继承遍历的最大层数常规无需改动[ui] columns[duration, time, command]交互搜索列从左到右选中指示列恒在首位。支持字符串或对象{ type ..., width N, expand true }形式可用列duration(5)、time(8)、datetime(16)、directory(20)、host(15)、user(10)、exit(3)、command(占满剩余空间)。expand true只允许一列默认command独占源码中Ui::validate()会拒绝多列同时 expand[ui] syntax_highlighttrue搜索结果按运行 shell 语法高亮bash/zsh/sh 用 bash 文法fish 用 fish 文法无文法的 nu/xonsh/PowerShell 不高亮颜色可用主题的Syntax*键定制见 theming。tree-sitter 无法构建的平台不可用AI 相关设置[ai]独立成篇见 ai/settings。环境变量覆盖速记ATUIN_CONFIG_DIR覆盖配置目录文件固定为其中的config.toml由Settings::get_config_path()读取ATUIN_前缀变量ATUIN_SYNC_ADDRESS、ATUIN_SEARCH_MODE、ATUIN_DAEMON__ENABLED等优先级高于配置文件NO_MOTION等价于prefers_reduced_motion trueATUIN_TMUX_POPUP置false可单会话禁用 tmux popupATUIN_SHELL由 shell init 脚本注入用于search.shells auto的当前 shell 识别ATUIN_THEME_DIR覆盖主题目录。调试思路小结用atuin config get key --resolved确认最终生效值排除文件里写了但没生效用--verbose对照文件值 vs 解析值快速定位是默认值、文件还是环境变量在起作用修改表/数组配置history_filter、search.filters、extra_headers时直接编辑 config.toml——set明确不支持且会在校验失败时拒绝写入担心改动写坏配置时先atuin config print备份当前内容涉及daemon-fuzzy、daemon socket 或 tmux popup 的配置变更记得重启 shell 或重启 daemon 后再验证。【免费下载链接】atuin✨ Making your shell magical项目地址: https://gitcode.com/gh_mirrors/at/atuin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考