Battery: Update description and add caveats to reduce installation confusion

[johnmcdowell]

Important: Do not tick a checkbox if you haven’t performed its action. Honesty is indispensable for a smooth review process.

In the following questions <cask> is the token of the cask you're submitting.

After making any changes to a cask, existing or new, verify:

• [ X ] The submission is for a stable version or documented exception.
• [ X ] brew audit --cask --online <cask> is error-free.
• [ X ] brew style --fix <cask> reports no offenses.

Additionally, if adding a new cask:

• Named the cask according to the token reference.
• Checked the cask was not already refused.
• Checked the cask is submitted to the correct repo.
• brew audit --cask --new <cask> worked successfully.
• HOMEBREW_NO_INSTALL_FROM_API=1 brew install --cask <cask> worked successfully.
• brew uninstall --cask <cask> worked successfully.

---

This cask appeared to install the battery CLI, but the CLI doesn't work or isn't present unless the macOS app is run at least once. This change both:

• Makes it more obvious that there is an app
• Makes it clear that the CLI will not work unless the app is run once

[johnmcdowell]

Looks like somehow I accidentally sync'd other commits to the repo into my pull request.

I only intended to change Casks/b/battery.rb.

Is it each to proceed from here?

[p-linnane]

/rebase

[p-linnane]

Thanks for the PR. I've rebased it.

caveats are reserved for idiosyncrasies with actual installation from Homebrew specifically. If this is how the application behaves when you install it directly from upstream, we should not add caveats.

[johnmcdowell]

caveats are reserved for idiosyncrasies with actual installation from Homebrew specifically. If this is how the application behaves when you install it directly from upstream, we should not add caveats.

Depends what you mean by upstream.

If you install the battery CLI directly with different commands (curl -s https://raw.githubusercontent.com/actuallymentor/battery/main/setup.sh | bash), then the CLI works.

This cask actually just installs a macOS app. If you run the app, it will then install the CLI.

Currently it's confusing that cask description says it installs the CLI, but when you brew install battery you don't get a CLI. You have to figure out that there is a new macOS application which needs to be run at least once, as it completes the install of the CLI when first run.

I suggest that either:

• The cask could invoke the included macOS app on brew install battery such that the promised CLI is installed
• The cask description should not claim to install a CLI

Separately, I can also work with the battery maintainer to improve the battery github documentation to make clear that brew install battery doesn't install a CLI directly, but I don't love requiring users to find the documentation that explains why brew install doesn't do what one would expect from the description.

[johnmcdowell]

Reflecting on this more-- what I was hoping for was a homebrew acceptable way to communicate to users that this battery cask is the battery app that also installs the battery CLI when the app is first run.

Right now at the very least, the current cask description of its being the battery CLI is just wrong.

I would have thought the caveat I added that you need to run the app to complete the CLI install would be fine. If it's really not kosher per homebrew standards, what is the right way to communicate this?

Maybe we squeeze it into the cask description, like: "App for managing the battery charging status. Installs CLI on first use."

It's an improvement and would have helped me when I couldn't find the CLI after brew install battery, but the downside is I'm not sure who actually reads the cask descriptions.

Perhaps homebrew just expects the maintainers of the battery project to better document externally that if you want the CLI to work, you can either install this cask and run the app once, or to install the CLI directly (with curl, until someone makes a homebrew battery-cli formula)...

[p-linnane]

Does the .app have the CLI in it but it's just not installed til the .app is run? If so, we can add a binary stanza to install it at the same time.

[johnmcdowell]

Does the .app have the CLI in it but it's just not installed til the .app is run? If so, we can add a binary stanza to install it at the same time.

I'm not sure this makes sense as the macOS app is coded to look for the cli in /usr/local/bin as opposed to the homebrew folder and will install it again if it's not there. Separately, the CLI install actually has some logic around another dependency and permissions, etc, that I don't think we would want to duplicate in the homebrew logic even if we could.

Based on what I've learned here, I've removed the caveats per your instruction and update the PR to just clarify the description.

The new description explains that this cask is an app, not just a cli, and that if you're expecting the CLI you need to run the app first.

I am separately working with the battery maintainer to clarify the README as well.(actuallymentor/battery#272)

[miccal]

Thank you @johnmcdowell.