{"id":37433984,"url":"https://github.com/alterationx10/ursula","last_synced_at":"2026-01-16T06:38:27.544Z","repository":{"id":37004629,"uuid":"495230818","full_name":"alterationx10/ursula","owner":"alterationx10","description":"A slim framework to make CLI apps in ZIO","archived":false,"fork":false,"pushed_at":"2024-07-26T21:26:32.000Z","size":81,"stargazers_count":10,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-10T22:55:07.222Z","etag":null,"topics":["cli","scala","zio"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alterationx10.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-23T02:17:40.000Z","updated_at":"2024-07-26T21:26:35.000Z","dependencies_parsed_at":"2024-07-26T23:00:08.939Z","dependency_job_id":null,"html_url":"https://github.com/alterationx10/ursula","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/alterationx10/ursula","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alterationx10%2Fursula","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alterationx10%2Fursula/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alterationx10%2Fursula/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alterationx10%2Fursula/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alterationx10","download_url":"https://codeload.github.com/alterationx10/ursula/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alterationx10%2Fursula/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28477906,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","scala","zio"],"created_at":"2026-01-16T06:38:27.483Z","updated_at":"2026-01-16T06:38:27.534Z","avatar_url":"https://github.com/alterationx10.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ursula\n\nA slim framework to make Scala CLI apps in ZIO.\n\n## Project Status\n\nThis project is still in (very) early development, but feel free to give it a\ntry - I'd love to hear any feedback you have. I had been publishing early artifacts to CloudSmith,\nbut I'll be updating to Maven Central soon.\n\n## Cross Compatibility\n\nThis project was steering towards a focus on Scala Native, however I think I painted myself into a corner with that.\nNow, this project is going to focus on just the JVM, and Scala 3. It's also going to be very scala-cli focused.\n\n## Anatomy of the Framework\n\nHere is a general overview if of the pieces fit together.\n\n### How it works: UrsulaApp\n\nYou only need to make an object that extends the `UrsulaApp` trait, and provide\na `Seq[Command]`, which are your actions you wish to be available in your\napp. `UrsulaApp` extends `ZIOAppDefault`, and wires up everything needed for the\n`run` method automatically! It parses the arguments passed, and uses that to\npull out the `Command` provided, and runs accordingly, passing on the arguments\nto it.\n\nThere are some [built in commands](#built-in-commands) provided, such as the\n`HelpCommand` and `ConfigCommand`, that are also automatically injected. This\nmeans that even if you only have:\n\n```scala\nobject App extends UrsulaApp {\n  override val commands: Seq[Command] = Seq.empty\n}\n```\n\nyou already have a functioning cli app that has a `help` command that prints all\nthe available commands accepted (as little as they are so far), as well as a\n`config` command that will let a user set/get/delete values from the apps config\nfile (defaulted to `$home/.ursula/config.json`)\n\nAt this point, you need only implement some `Command`s that wrap the\nfunctionality you desire, and add them to the `commands: Seq`.\n\n### Commands\n\nThere is a `trait Command` to extend, and the essence of this the\nimplementation of\n\n```scala\ndef action(args: Chunk[String]): ZIO[UrsulaServices, Throwable, ?]\n```\n\nYou consolidate all of your ZIO logic you want to run in this method that will\npass in arguments that are `Chunk[String]` and returns a\n`ZIO[UrsulaServices, Throwable, ?]`. Note that the return value is `?` - the\nactual result is discarded to `.unit`, as `Commands` are meant to be a\none-off calls from the main entry point, and generally not composed with\nother `Command`s.\n\n`UrsulaServices` are a collection of built in ZIO services that are available\nfor you to use (or not at all, if you don't want to!). `UrsulaServices` are\nbundled in via the `UrsulaApp`, so you don't need to provide them with your\nlogic - you just need to provide all of the other resources to run your won\nlogic (i.e. you can `.provideSome[UrsulaServices](...yourDepsHere))` and not\nhave to worry about it.\n\nThere are a few other items to implement, such as\n\n```scala\n  val trigger: String\nval description: String\nval usage: String\nval examples: Seq[String]\n```\n\n`trigger` is the String that should be used at the start of your CLI arguments\nto call that particular command. The others are simple informational strings\nabout your command - and those are automatically used by the built-in help\ncommand to print documentation!\n\nTwo other important things to declare are\n\n```scala\n  val flags: Seq[Flag[?]]\nval arguments: Seq[Argument[?]]\n```\n\n[Flags](#flags) and [Arguments](#arguments) are discussed below, but know that\nthey are simple traits to extend that help you parse/provide values for the\n`args` passed in - and they too have some simple Strings to implement that\nprovide auto documentation for your app. At the end of the day, you can just\nparse the `args` on your own in your ZIO logic - but usage of the `Flag`s\nand`Arguments` should hopefully simplify things for your and your apps users.\n\n#### Built-In Commands\n\n- HelpCommand - handles the printing of documentation\n- ConfigCommand - manipulates a simple JSON config file\n\n### Flags\n\nFlags (`trait Flag[R]`) are non-positional arguments passed to the command.\nFlags can be generally used as either an argument flag, which expects the next\nelement in the command arguments to be parsed as type `R`, or boolean flags\nwhich do not (i.e. present/not present).\n\nThe\n[source code](ursula/shared/src/main/scala/com/alterationx10/ursula/args/Flag.scala)\nis fairly well documented at this point. Some general highlights are that it has\nthings built in to\n\n- parse argument(s) that can then be used in you `Command`\n- declare conflicts with other flags\n- declare requirements of other flags\n- provide defaults, of ENV variables to be used\n\n### Arguments\n\nArguments (`trait Argument[R]`) are _positional_ arguments passed to the\ncommand, and are to be parsed to type `R`\n\nThe\n[source code](ursula/shared/src/main/scala/com/alterationx10/ursula/args/Argument.scala)\nis fairly well documented at this point. Some general highlights are that you\ncan encode the parsing logic.\n\n### Built-In Services\n\n`UrsulaServices` is the sum of all services that are automatically provided in\nthe `R` channel of your commands `action` zio. See below for more info on each.\n\n#### CliConfig\n\nThis service allows you to get/set/delete keys from the apps config file. Behind\nthe scenes, the `UrsulaApp` will automatically read the config file at start,\nand load it into an in memory `Map`. This `Map` is what backs this service, and\nif the state becomes dirty (i.e. a `set` or `delete` is used), then after your\n`Command` logic has run, it will persist the `Map` back to disk.\n\n## Using in your project\n\nAs mentioned above, I'll be moving artifacts to maven central soon, so check back for soon artifacts/versions.\n\n## Other Projects\n\nIt's always good to have options 😉.\n\nThere is an official [zio-cli](https://github.com/zio/zio-cli) project out\nthere, and I encourage you to check that out too! I feel maybe one large\ndifference is just how apps are structured/built, driven mostly by my\nmotivations outlined [above](#about). A lot of my inspiration for this project\ncomes from [oclif: Node.JS Open CLI Framework ](https://github.com/oclif/oclif).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falterationx10%2Fursula","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falterationx10%2Fursula","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falterationx10%2Fursula/lists"}