Beton CLI Docs

Installation #

Beton requires Python 3.10 or later. The recommended path uses the npm wrapper, which also requires Node.js 18+ and npm. It is not distributed as a PyPI package: do not run pip install beton or pip install beton-cli. The wrapper downloads the official tagged source release and installs it locally into an isolated runtime.

Recommended npm installation #

Install the published npm wrapper from ordinary PowerShell, Command Prompt, macOS Terminal, or Linux shell. The wrapper downloads the official v0.5.0 backend release and creates an isolated runtime in the user data directory.

npm install -g beton-cli
beton doctor
beton --version

Prerequisites #

Check that Python and pip are available in the shell where you plan to install Beton.

python --version
python3 --version
pip --version

Alternative: install the published source release #

git clone --branch v0.5.0 --depth 1 https://github.com/itsjustayush/beton-cli.git
cd beton-cli
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
beton doctor

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1

# Open a new VS Code / PowerShell terminal
beton doctor
beton --version

git clone --branch v0.5.0 --depth 1 https://github.com/itsjustayush/beton-cli.git
Set-Location beton-cli
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\beton.exe doctor

The installer uses pip only as the local build installer for the cloned source tree. It does not download Beton from PyPI. It creates a user-level beton command shim in %USERPROFILE%\bin and adds that directory to your user PATH. Open a new terminal after installation. If Git prints a nonfatal annotated-tag warning but exits successfully and switches to a commit, the shallow release checkout succeeded.

Development install #

python -m pip install -e ".[dev]"

For a quick checkout without installing an editable package, run the module directly from the repository:

PYTHONPATH=src python -m beton --help

Quickstart #

Once installed, Beton keeps the everyday workflow intentionally small: see the interface, open something, search, save a note, run a timer, and inspect the environment.

beton
beton help
beton open --help
beton search --help

beton open chrome
beton open https://github.com
beton --dry-run open ~/Documents

beton search "python tutorials"
beton search "beton-cli" --engine github
beton search "private query" --browser chrome --incognito

beton note "finish project" --tag work
beton today
beton path --kind notes

beton timer 25m --label Focus

beton open #

beton open is the universal launcher. Pass a URL, configured alias, filesystem path, or bare application name and Beton resolves it to the appropriate local action.

Syntax #

beton open <target> [--browser BROWSER] [--incognito]
beton --dry-run open <target>

Target resolution order #

Beton checks the input in order and stops at the first match.

Inputs that look like paths but do not exist are rejected rather than guessed. This prevents a typo such as ./reports from silently becoming an application launch.

Examples #

beton open https://github.com
beton open https://github.com --browser chrome
beton open https://github.com --browser firefox --incognito

beton open chrome
beton open youtube
beton open github

beton open ~/Documents
beton open ./report.pdf
beton open /etc/hosts

beton open spotify
beton open code
beton open slack

Built-in aliases #

beton search #

beton search constructs a properly URL-encoded search URL and opens it in a browser. Defaults come from the command's options or your local configuration.

Syntax and flags #

beton search <query> [--engine ENGINE] [--browser BROWSER] [--incognito]

Examples #

beton search "python tutorials"
beton search "async python" --engine duckduckgo
beton search "react hooks" --engine youtube
beton search "typer library" --engine github
beton search "python typer" --browser chrome
beton search "private query" --browser edge --incognito

beton note and beton today #

Notes are local, append-only Markdown entries. They are not uploaded or synced by Beton. Use beton today to review entries written on the current date.

Syntax and flags #

beton note <text> [--tag TAG]
beton today

Examples and file format #

beton note "finish the project proposal"
beton note "review chapter 3" --tag study
beton note "deploy to staging" --tag work
beton note "buy groceries" --tag personal
beton today

Each entry includes an ISO 8601 timestamp with timezone offset. Tagged entries include the tag inline as a Markdown code span.

- **2024-06-14T09:32:01+05:30** `#work` — deploy to staging
- **2024-06-14T09:35:08+05:30** — finish the project proposal

beton timer #

The timer runs a foreground countdown in the current terminal. It displays progress at the start, every completed minute, and during the final five seconds before announcing completion.

beton timer <duration> [--label LABEL]

beton timer 25
beton timer 25m --label "Focus Session"
beton timer 5m --label "Short Break"
beton timer 90s
beton timer 2h --label "Deep Work"

# Preview without waiting
beton --dry-run timer 25

Utility commands #

Utilities inspect the local environment. They are designed to be read-only: they do not modify configuration, write notes, kill processes, or execute destructive actions.

Print the current text clipboard. Output is capped at 2,000 characters by default.

beton clip
beton clip --full
beton --dry-run clip

Linux typically requires xclip or xsel. macOS and Windows use native mechanisms. The --full flag disables truncation.

Show the data directory, config file, or notes file path.

beton path
beton path --kind data
beton path --kind config
beton path --kind notes

List configured application aliases and report whether each executable is detected on PATH. URL aliases are managed separately in configuration.

beton apps

Alias     Target          Status
chrome    google-chrome   detected
code      code            detected
spotify   spotify         not on PATH

Find files below a root directory using a glob pattern. The root defaults to your home directory and results default to 50.

beton find <pattern> [--in ROOT] [--limit N]
beton find "*.pdf"
beton find "*.md" --in ~/Documents
beton find "*.py" --in ~/projects --limit 20

List running processes with optional case-insensitive name filtering. Beton reports processes but never kills or changes them.

beton process [QUERY] [--limit N]
beton process
beton process chrome
beton process python --limit 10

Inspect Python, operating system, data directory status, path opener availability, and detected browsers.

beton doctor
beton --plain doctor

Run it immediately after installation and again when a feature fails. Missing optional capabilities do not prevent unrelated commands from working.

beton system #

Trigger a selected OS-level session or power action. Beton runs with the launching user's permissions and uses a confirmation prompt for disruptive actions by default.

beton system <action> [--yes]
beton --dry-run system <action>

beton system lock
beton system sleep --yes
beton --dry-run system restart
beton system shutdown --yes

beton config #

View or update local JSON configuration. The current CLI supports top-level settings with show and set.

beton config show
beton config set <key> <value>

beton config set browser chrome
beton config set search_engine duckduckgo
beton config set plain true
beton --verbose config set browser firefox

Values of true and false are parsed as booleans. Other values remain strings. Configuration changes are written immediately to the local config file.

beton help, beton version, and beton --version #

Use help and version metadata to understand the installed CLI. The read-only --version flag prints the current version; version --upgrade refreshes an npm installation through npm or safely upgrades an official source checkout.

beton help
beton --help
beton open --help
beton search --help
beton version
beton --version
# Output example: BETON 0.5.0

beton help presents a compact table of core commands and examples. --help shows command-specific arguments and flags. beton version prints the installed version without changing anything. Running beton by itself shows the brand screen; beton beton is not a valid command.

beton version --upgrade #

When Beton was installed with npm, this command updates the global npm wrapper and its isolated Python runtime. When Beton was installed from the official GitHub source checkout, it updates the checkout and refreshes the active Python environment without a manual reinstall:

beton version --upgrade
beton version --upgrade --yes
beton --dry-run version --upgrade

beton version --upgrade
beton version --upgrade --yes
beton --dry-run version --upgrade

# No-PATH fallback
.\.venv\Scripts\beton.exe version --upgrade

For npm installations, the upgrade uses npm install --global beton-cli@latest. For source checkouts, it is limited to the official itsjustayush/beton-cli remote on the main branch; it refuses to overwrite uncommitted changes, uses a fast-forward-only pull, asks for confirmation by default, and reinstalls the updated local source into the active Python environment. --dry-run previews the operation; --yes skips the confirmation prompt.

Settings #

Beton stores its settings locally in JSON. You can print them with beton config show and change them with beton config set.

beton config set browser firefox
beton config set search_engine duckduckgo
beton config set plain true
beton config show

Aliases #

Aliases let you assign short names to applications, URLs, and folders. Pass the alias to beton open instead of typing the full target.

Alias entries live under the aliases key in config.json. The application aliases are listed by beton apps; URL and path aliases are managed directly in the JSON file.

{
  "aliases": {
    "docs": { "kind": "url", "value": "https://docs.example.com" },
    "notes": { "kind": "path", "value": "/home/user/notes" },
    "terminal": { "kind": "app", "value": "wt" }
  }
}

beton apps
beton open docs
beton open notes
beton open terminal

Data storage #

Beton is local-first. Its core footprint consists of a configuration file and a Markdown notes file in the platform's standard application-data directory.

beton path
beton path --kind config
beton path --kind notes

BETON_HOME=/tmp/beton-test beton note "isolated test note"
BETON_HOME=/mnt/external/beton beton path

Browser control #

Choose a browser per command or save a persistent default. Explicit browser selection is required when you want private browsing.

beton search "python docs" --browser chrome
beton search "python docs" --browser edge
beton search "python docs" --browser firefox
beton open https://github.com --browser firefox

beton config set browser chrome

Dry run #

--dry-run is a global flag placed immediately after beton. It describes an action and exits without opening browsers, writing files, or sending system commands.

beton --dry-run open https://github.com
beton --dry-run search "electrostatics"
beton --dry-run system restart
beton --dry-run timer 25
beton --dry-run clip

Dry runs are useful for checking URL and alias resolution, verifying configured browser and search engine behavior, inspecting system commands before a restart or shutdown, and testing scripts safely.

Plain mode #

Rich formatting is useful in interactive terminals, but scripts, logs, CI runners, and minimal shells often need undecorated text. Use --plain for one invocation or save plain=true permanently.

beton --plain doctor
beton --plain note "meeting notes"
beton --plain today

beton config set plain true
beton config set plain false

The content stays the same; only panels, colors, icons, and other decorative Rich formatting are removed.

Global flags #

Global flags appear before the subcommand and affect the invocation consistently.

beton [GLOBAL FLAGS] <command> [command args and flags]

beton --dry-run --plain search "test query"

Troubleshooting #

When in doubt, start with beton doctor. It reports Python, platform, data-directory, path-opener, and browser capabilities in one place.

beton: command not found #

Beton may not be installed in the active virtual environment, or the environment’s script directory may not be on PATH. Beton is installed from the official GitHub source release, not from PyPI.

cd beton-cli
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m beton --help

# Confirm the installed source version
beton --version

On Windows PowerShell, activate with \.\.venv\Scripts\Activate.ps1. If you are using a development checkout, replace python -m pip install -e . with python -m pip install -e ".[dev]".

Clipboard access fails #

Linux clipboard access typically needs xclip or xsel. Install one with your package manager, then rerun beton doctor.

sudo apt install xclip
# or
sudo apt install xsel

Browser not detected #

Explicit browser values require Beton to locate the browser executable. Run beton doctor, ensure the executable is installed and discoverable on PATH, or use --browser default as a fallback.

--incognito is rejected #

Private mode requires a named browser. Use one of the following forms:

beton search "query" --browser chrome --incognito
beton search "query" --browser firefox --incognito
beton search "query" --browser edge --incognito

System action returns permission denied #

Sleep, shutdown, and restart depend on platform permissions. First inspect the command with dry run. Then review your platform's policy configuration rather than routinely running Beton as root.

beton --dry-run system sleep
beton --dry-run system shutdown

Diagnostics show missing capabilities #

Notes do not appear in beton today #

beton today filters by the current date. Check the data directory and timestamps, especially if BETON_HOME differs between terminal sessions.

beton path
printf '%s\n' "$BETON_HOME"

beton path
$env:BETON_HOME

Older notes remain in the Markdown file even though they are not shown by today.