Metadata-Version: 2.4
Name: tildagon-cli
Version: 0.1.0
Summary: Command-line utility for managing a Tildagon (EMF Camp badge) over USB
Project-URL: Homepage, https://codeberg.org/andypiper/tildagon-cli
Project-URL: Repository, https://codeberg.org/andypiper/tildagon-cli
Author: Andy Piper
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: click
Requires-Dist: mpremote
Requires-Dist: rich
Description-Content-Type: text/markdown

# tildagon-cli

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/)

A command-line utility for managing a [Tildagon](https://tildagon.badge.emfcamp.org/) (EMF event badge) over USB.

A browsable command reference is also available in [`manual.html`](manual.html) — open it directly in a browser.

## Table of Contents

- [Background](#background)
- [Install](#install)
- [Usage](#usage)
- [License](#license)

## Background

`tildagon.py` wraps [`mpremote`](https://docs.micropython.org/en/latest/reference/mpremote.html) to run MicroPython commands on the badge over USB serial. It can manage apps, WiFi credentials, and settings without needing to interact with the badge UI. I wanted to be able to do things like adding and removing apps in bulk at the CLI, so I made this. Built on Linux, but should be fine on other OSes - assuming things like port are specified in a platform-specific manner.

## Install

**Requirements:** Python 3.13+

**From PyPI** (recommended — installs the `tildagon` command plus `mpremote` automatically):

```sh
uv tool install tildagon-cli
```

`pipx install tildagon-cli` or `pip install tildagon-cli` work the same way if you don't use `uv`.

**Run without installing:** `uv run` accepts a URL directly, so the script can be run with no local checkout and no separate `mpremote` install — dependencies (`click`, `rich`, `mpremote`) are declared inline and handled automatically by `uv`:

```sh
uv run https://codeberg.org/andypiper/tildagon-cli/raw/branch/main/tildagon.py -- --help
```

**Local checkout without `uv run`:**

```sh
chmod +x tildagon.py
ln -s "$(pwd)/tildagon.py" ~/.local/bin/tildagon
```

(this form still needs `mpremote` installed separately: `pip install mpremote`.)

**Shell completion (zsh):**

```sh
_TILDAGON_COMPLETE=zsh_source tildagon > ~/.zfunc/_tildagon
```

Add to `~/.zshrc` if not already present:

```zsh
fpath+=~/.zfunc
autoload -Uz compinit && compinit
```

## Usage

```sh
uv run tildagon.py [--port /dev/ttyACM0] <command>
```

On Linux, the device is often `/dev/ttyACM0` (default). Override with `--port` / `-p`.

Every command accepts `-h` as well as `--help`, e.g. `tildagon apps install --help`.

### Commands

#### `info`

Show firmware version, MicroPython version, frontboard type, and attached hexpansions.

```sh
uv run tildagon.py info
```

#### `battery`

Show battery level and charge state.

```sh
uv run tildagon.py battery
```

#### `df`

Show flash filesystem usage on the badge.

```sh
uv run tildagon.py df
```

Wraps `mpremote df`. If `Avail (KB)` is negative and `Use%` is over 100%, the badge's flash is full — that shows up as apps crashing on `OSError: 28` (`ENOSPC`) whenever they try to write settings or cache files. Free space with `apps uninstall`.

#### `name`

Get or set the badge display name.

```sh
uv run tildagon.py name get
uv run tildagon.py name set "Jonty"
```

#### `wifi`

Read or update WiFi credentials.

```sh
uv run tildagon.py wifi get
uv run tildagon.py wifi set <ssid> <password>
```

#### `autoexec`

Get, set, or clear the app that launches automatically at startup instead of the default launcher.

```sh
uv run tildagon.py autoexec get
uv run tildagon.py autoexec set "Settings"
uv run tildagon.py autoexec clear
```

`autoexec set` writes `/autoexec.bat` with the exact app name as shown in the launcher menu. Requires newer firmware.

#### `dev`

Get, enable, or disable developer mode.

```sh
uv run tildagon.py dev get
uv run tildagon.py dev enable
uv run tildagon.py dev disable
```

Developer mode adds a handful of (shark-prefixed) debug apps to the launcher menu (BoopSpinner, Menu demo, Text demo, Inhibit LEDs, ESPNow ping), and unlocks manual editing of a hexpansion's unique ID in the Hexpansions app. Developer mode can be toggled on the badge itself by pressing confirm 5 times on the "Software version" line in Settings; there is no in-UI way to turn it back off, so use `dev disable`.

#### `apps`

List, install, or uninstall badge apps.

```sh
uv run tildagon.py apps list
uv run tildagon.py apps install path/to/myapp [path/to/another]
uv run tildagon.py apps uninstall <directory> [<directory> ...]
uv run tildagon.py apps uninstall
```

`apps list` shows the display name alongside the directory name (needed for uninstall), reading metadata from either `tildagon.toml` or `tildagon.json` (the app store writes the latter). Installing reboots the badge automatically. Run `apps uninstall` with no arguments to pick apps to remove from a numbered list instead of copying directory names by hand.

#### `store`

Search and install apps from the [Tildagon App Store](https://apps.badge.emfcamp.org/).

```sh
uv run tildagon.py store search [query] [--category Games,Apps] [--author x] [--license MIT] [--service github] [--capability neopixels] [--requires nmea] [--supports x] [--limit 10]
uv run tildagon.py store install [<code> ...] [--category Games,Apps] [--author x] [--license MIT] [--service github] [--capability neopixels] [--requires nmea] [--supports x] [--limit 10]
uv run tildagon.py store url <code> [<code> ...]
uv run tildagon.py store failures
```

`store url` prints the app store page for one or more codes (from `store search`), e.g. to open in a browser. `store search` and `store install` take the same filters (comma-separated, matched against the [store API](https://apps.badge.emfcamp.org/api-docs)) and sort newest first, so `store search --limit 10` shows the 10 most recently released apps (the table title shows "N of TOTAL" when a limit truncates the match count). `--capability` filters on apps that require *or* support a given capability; `--requires`/`--supports` narrow to just one side. Short names like `neopixels` expand to the full [capability registry](https://tildagon.badge.emfcamp.org/capabilities/registry/) URL automatically. Run `store install` with no codes (optionally filtered) to browse a numbered list and pick apps interactively instead of looking up codes first; multiple codes are resolved in a single store request. `store failures` lists app submissions that failed to publish, with the validation reason — useful when an app you expect isn't showing up.

#### `settings`

Show all badge settings (passwords redacted by default), or get/set/clear a single key.

```sh
uv run tildagon.py settings
uv run tildagon.py settings --raw
uv run tildagon.py settings get <key>
uv run tildagon.py settings set <key> <value>
uv run tildagon.py settings clear <key>
```

#### `monitor`

Open the badge REPL for debugging. Useful for seeing tracebacks from crashing apps.

```sh
uv run tildagon.py monitor
```

Press Ctrl-C to interrupt the running app, Ctrl-D to soft-reset while staying connected, Ctrl-] to exit.

#### `reboop` / `reboot`

Reset the badge.

```sh
uv run tildagon.py reboop
```

## License

[MIT](LICENSE) © [Andy Piper](https://andypiper.me)
