{"id":16681742,"url":"https://github.com/casidiablo/macondo","last_synced_at":"2026-05-14T21:36:47.502Z","repository":{"id":140747830,"uuid":"270509400","full_name":"casidiablo/macondo","owner":"casidiablo","description":"generic, polyglot commands platform","archived":false,"fork":false,"pushed_at":"2020-12-31T05:18:10.000Z","size":50,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-09-24T23:41:18.714Z","etag":null,"topics":["commands","docker"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/casidiablo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2020-06-08T03:08:07.000Z","updated_at":"2022-02-15T09:02:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"6c094b60-f064-41ef-8e08-bb3a111b07f8","html_url":"https://github.com/casidiablo/macondo","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/casidiablo/macondo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casidiablo%2Fmacondo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casidiablo%2Fmacondo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casidiablo%2Fmacondo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casidiablo%2Fmacondo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/casidiablo","download_url":"https://codeload.github.com/casidiablo/macondo/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casidiablo%2Fmacondo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278786686,"owners_count":26045588,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["commands","docker"],"created_at":"2024-10-12T14:05:09.787Z","updated_at":"2025-10-07T13:54:49.099Z","avatar_url":"https://github.com/casidiablo.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"[experimental] generic, polyglot commands runner.\n\nWrote a blogpost about it here: https://cristian.io/post/macondo/\n\n# Install\n\n- Download binary [Linux](https://github.com/casidiablo/macondo/releases/download/0.1.1/macondo-0.1.1-linux) | \n  [MacOS](https://github.com/casidiablo/macondo/releases/download/0.1.1/macondo-0.1.1-osx)\n  (no Windows support yet)\n- Make it available in your `PATH`\n- Add a repository: `macondo repo add [FILE|DIR|HTTP]`\n\n## Motivation\n\nScripts, commands, applications, tools, etc. are useful. However, as they get\ncomplex it is hard to ensure that they will run as expected in ALL machines:\n\n- **Dependencies**: scripts assume certain commands will be installed in the system.\n  At best, they require the user to install them before hand, at worst they are\n  hard to procure on the user's system or it is necessary to run a _specific_\n  version.\n- **Runtime**: some scripts run atop specific runtimes or environments. e.g.\n  Python 3.6, Ruby 2.6, etc. At best, users annoyingly have to install/learn to\n  use such stack; at worst, the version of the required runtime conflicts with\n  other scripts or programs.\n- **Local environment**: some scripts assume/require the user to have certain\n  things on their environments (e.g. credentials files like\n  `~/.aws/credentials`, config files like `~/.kube/config`, etc.)\n\nUsually, such adversities can be overcome by packaging the command or tool in a\nDocker container. This is a neat solution that _solves_ the previous two points.\n\nHowever, in order to effectively use such tool (besides installing Docker), it\nis necessary to understand the way the tool was packaged:\n\n- What's the proper way to run it it?\n- Does it need volumes to run correctly?\n- Which user does it need to run with?\n- Do I need to expose ports? _TODO_\n- Do I need to forward an environment variable? _TODO_\n\n## Ideal use cases\n\nAs a developer:\n\n- I can build a command/tool/script, etc. using whatever technology, runtime or\n  tooling I want\n- I can easily build/package/distribute such tools\n\nAs a user:\n\n- I can run any commands using a single tool\n- I can run commands without installing extra dependencies\n- I can run commands withoug installing extra runtimes (other than Docker)\n- I can run commands without knowing how they were built or how they run (no\n  Docker knowledge required)\n- I can run commands that interact with my local filesystem without manually\n  mounting volumes into the containers that run the commands.\n- I can easily add/upgrade/remove commands\n\n## Proposed implementation\n\n`macondo` is single binary that can be used to run _commands_ (via Docker). A\n_command_:\n\n- is a script, application, tool, or anything that can be run\n- it self describes how build/package it (i.e. into a Docker image)\n- it specifies whether it needs to access local volumes, and which ones\n- is polyglot: can be a bash script, or a python application, or a full fledged\n  JVM service.\n  \nCommands can be procured, dynamically, by adding config entries to the\n`~/.macondo` file, which contains commands' definitions (manifests), local paths\npointing to the source code of commands, links to web resources containing\ncommands' manifests,etc.\n\n### Example\n\nLet's take a look at an example of simple command (`show-something.mcd`):\n\n```bash\n#!/usr/bin/env bash\n# @from Dockerfile\n# @description Gets some data from an http resource as JSON, processes it and displays it as a table\n# @version 0.1.0\n\n# Use httpie to request data from a resource\nresponse=$(http GET https://some.web/resource.json)\n\n# Use jq to parse the response as TSV\nas_tsv=$(echo \"$respone\" | jq '.[] | select(.foo == \"bar\") | [.id, .someOtherField] | @tsv')\n\n# Format it as a table\nprintf \"ID\\tNAME\\n%s\" \"$as_tsv\" | column -t -s $'\\t'\n```\n\nSome notes on the previous command:\n\n- It depends on some tools being installed (`httpie`, `jq`, GNU's `column`, `bash`)\n- This just a Bash script. If you had all of those tools installed, you _could_,\n  in theory, just run it.\n- There are some annotations at the top:\n  - The `@from` annotation specifies how to procure the Docker image to run this\n    on. In this case, we are saying this command is accompanied by a\n    `Dockerfile` (an example is shown below), which would need to be built\n    before this command is run.\n  - `@description` is just metadata explaining what this command does.\n  - `@version` is just a way to track changes to the command.\n\nThe `Dockerfile` could look something like this in this case:\n\n```Dockerfile\nFROM alpine\nRUN apk --no-cache add httpie jq util-linux bash\n\nCOPY show-something.mcd /\nENTRYPOINT [\"bash\", \"/show-something.mcd\"]\n```\n\nAlternatively, it is possible to simplify the command by not even using a Dockerfile:\n\n```bash\n#!/usr/bin/env bash\n# @from AlpinePackages httpie jq util-linux\n# @description Gets some data from an http resource as JSON, processes it and displays it as a table\n# @version 0.1.0\n\n... the rest\n```\n\nThis would build an alpine-based Docker image on-the-fly to run the command on.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcasidiablo%2Fmacondo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcasidiablo%2Fmacondo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcasidiablo%2Fmacondo/lists"}