Holivia

Ruby client and command-line interface for the Holivia API.

The holivia executable is primarily used to manage Holivia backoffice data from the terminal: environments, authentication, selfcare content, objectives, and appointment diagnostics.

Coding agents can use SKILL.md as a downloadable usage guide for operating this CLI safely.

Requirements

Ruby 3.1 or newer
A Holivia account with API access

Installation

Install the CLI from RubyGems:

gem install holivia

If you want to use the gem from a Ruby application, add it to your bundle:

bundle add holivia

After installation, verify the executable is available:

holivia version

Setup

The CLI stores environment configuration in ~/.holivia/config.yml.

Show the current environment:

holivia env

Add an API environment:

holivia env add staging --url https://staging.example.com

Switch to an environment:

holivia env use staging

List configured environments:

holivia env list

Enable debug logging for the current environment when troubleshooting requests:

holivia env debug --true

Disable it again with:

holivia env debug --false

Authentication

holivia login

Or pass credentials directly:

holivia login --email user@example.com --password secret

Credentials are stored per environment in ~/.holivia/credentials.<env>.json. Access tokens are sent as bearer tokens, and the CLI automatically refreshes credentials after a 401 response when a refresh token is available.

Log out and remove stored credentials for the current environment:

holivia logout

Basic Usage

Show all available commands:

holivia --help

Discover valid selfcare enum values and item parameters:

holivia selfcare schema

List selfcare contents:

holivia selfcare index

Show one selfcare content:

holivia selfcare show 123

Create a selfcare content from flags:

holivia selfcare create \
  --title "Breathing exercise" \
  --locale fr \
  --content-type exercise \
  --duration 300 \
  --state draft

Create a full selfcare content tree from JSON:

holivia selfcare compose --file examples/compose.json

You can print a compose template with:

holivia selfcare compose --example

Create and update commands also accept JSON from standard input:

printf '{"title":"Breathing exercise","locale":"fr"}' | holivia selfcare create

List objectives:

holivia objective index

Filter objectives by code:

holivia objective index --code anxiety

Show video diagnostics for an appointment:

holivia appointment video-diagnostics 42

Files And Uploads

Selfcare create and update commands can upload images with --image <path>.

holivia selfcare update 123 --image cover.png

Slide item create and update commands can upload audio with --audio <path>.

holivia selfcare item create --slide-id 456 --item-type AudioItem --audio meditation.mp3

Compose is JSON-only. To attach an image to a composed content tree, update the returned content id afterward with holivia selfcare update <id> --image <path>.

Development

After checking out the repo, run:

bin/setup

Run the test suite with:

rake spec

Open an interactive console with:

bin/console

Install this gem onto your local machine with:

bundle exec rake install

To release a new version, update the version number in lib/holivia/version.rb, then run:

bundle exec rake release

This creates a git tag, pushes commits and tags, and publishes the .gem file to RubyGems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Holivia-Team/holivia-ruby.

License

The gem is available as open source under the terms of the MIT License.

Code Of Conduct

Everyone interacting in the Holivia project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the code of conduct.