Browser search and local tools#

Automexia offers explicit helpers for a few common lookups. They do not search your screen automatically, install tools, or replace your shell. The commands below come from the current public source; run automexia --help to confirm the commands in your development build.

Choose the kind of search#

The session-local amx helper is available only when the matching shell integration loads. You can use the same subcommands through automexia when the executable is on your PATH. A pre-existing shell command named amx keeps priority. AUTOMEXIA_AMX=0 before integration loads disables Automexia's helper without removing your own command.

Open the current folder in a file manager#

amx open hands an existing directory to your desktop file manager. With no argument it uses the current directory. For example, after changing into a project, run amx open . to inspect its files visually, or amx open "folder with spaces" for a child folder. amx open --preview . resolves the destination and prints JSON without launching the file manager. Outside an integrated shell, use automexia open.

This is a directory handoff, not a way to run a file or create a folder. A missing path, regular file, or unsafe path is rejected. Linux/BSD needs a graphical desktop and a configured directory handler; a headless server cannot open a local window. In Windows-backed WSL, the guest resolves its path before handing it to the Windows file manager and needs Python 3.10+ inside that distribution. A successful handoff request does not prove a window became visible. Preview can reveal a private path and can consult a mounted filesystem, so review its output before sharing it.

Open one file in your editor#

amx edit requests an existing regular file in the installed VS Code desktop handler. It does not install an editor or read the file contents. Relative paths use the current directory. Line and column numbers are one-based:

amx edit src/main.rs --line 42
amx edit src/main.rs --line 42 --column 7
amx edit --preview "src/example file.rs"

This is useful when terminal search identifies a file and line but you want to make the change in an editor. --preview resolves and prints the destination without launching anything. To choose VS Code Insiders once, use amx edit --editor vscode-insiders src/main.rs. For a persistent choice, put version = 1 and editor = "vscode-insiders" in amx.toml beside your user config.toml. The accepted values are vscode, vscode-insiders, and disabled. A one-time --editor cannot bypass disabled. Automexia does not use project-local amx.toml, EDITOR/VISUAL, or arbitrary editor command templates for this handoff.

An absent file, unsupported editor handler, or unsafe/ambiguous path fails rather than opening another target. On WSL, an installed guest Python 3.10+ resolves the guest path and the host editor receives its Windows-accessible location; Automexia does not install Remote-WSL or approve editor trust prompts. Preview may contain a private path. An acknowledged handoff is not proof that the editor finished opening the file.

Open the current repository or its issues#

amx repo uses installed Git to read the current repository's origin fetch URL and opens its GitHub.com or GitLab.com page in the default browser. amx repo issues chooses that repository's issue page. For a fork where the project lives under upstream, select it explicitly: amx repo issues --remote upstream --preview. The preview derives a URL from local Git metadata only; it does not contact the host or open a browser.

This helps after following a stack trace into a checked-out project or when you want to report an issue in the right repository. Check the preview first if a checkout has several remotes. Supported HTTPS and ordinary Git SSH remote forms are validated; unsupported/self-hosted domains, local paths, credentials in URLs, and ambiguous remotes are rejected rather than guessed. The command does not authenticate, fetch, push, or prove that you can access the remote page. WSL uses the selected guest repository and installed guest Git, not an unrelated Windows checkout. Preview may reveal a private repository name; do not publish it casually.

Search files or text locally#

Install rg (ripgrep) yourself. Change into the intended project first, because find searches the current directory and descendants. It uses literal fragments, not glob or regex syntax, and respects ripgrep's normal ignore/hidden/binary behavior plus additional excluded sensitive names. Those exclusions are not a complete secret scan.

amx find file config.toml
amx find text "timeout"
amx find text --preview "timeout"

Preview shows the client and arguments without searching. A query beginning with - needs the conventional -- separator. Results are bounded; if a large project hits a limit, move into a smaller directory or refine the literal. No match is an ordinary empty result. If you need regexes, hidden files, binary search, or a byte-accurate result, run rg directly.

Read offline command examples#

Install tealdeer (tldr) and prepare its cache with its own command when you choose to allow a download. amx explain git log asks the local cache for examples; it does not execute them, refresh the cache automatically, or replace the tool's own documentation. Use amx explain --preview tar to inspect the intended invocation. Review every example's placeholders and side effects before using it.

If ripgrep or tealdeer is missing, Automexia reports that rather than installing a substitute. Press Ctrl+C to cancel an active lookup. In WSL, the guest needs its own installed tools and Python 3 for the bounded guest helper; a Windows installation is not silently reused.

Open a browser search deliberately#

amx search supports google, github (repositories), youtube, and ddg. amx docs supports official-site filters for kubernetes, docker, rust, python, git, and terraform. amx google is a Google-specific compatibility command. Unknown provider/tool names fail rather than choosing another destination.

amx search github "terminal emulator"
amx search ddg linux permissions
amx docs docker compose
amx google 'C++ & Rust'
amx search github --print-url 'C++ & Rust'

Place --print-url before search terms to see the encoded URL without opening a browser. Quote punctuation so your shell does not interpret &, |, or $. The helper hands a URL to the OS default browser; it does not fetch results into the terminal or guarantee that the destination loads. Your shell may keep query history, and the chosen browser/search service receives the query when you open it. Never put secrets or private operations data in a search.

Choose another tool when appropriate#

amx find is for a quick bounded literal lookup, not a source-code index. amx explain is for cached examples, not authoritative command documentation. amx docs opens a browser, not an authenticated provider connection. For more control, use rg, your project's search tool, the command's --help, or the official documentation directly.