{"id":22396550,"url":"https://github.com/theholocron/holocron","last_synced_at":"2026-07-01T20:00:54.484Z","repository":{"id":260215330,"uuid":"880623594","full_name":"theholocron/holocron","owner":"theholocron","description":"The command-line client designed to support The Holocron.","archived":false,"fork":false,"pushed_at":"2026-06-30T00:25:19.000Z","size":2312,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-30T01:11:02.802Z","etag":null,"topics":["bootstrap","command-line","holocron","nodejs","typescript"],"latest_commit_sha":null,"homepage":"https://docs.theholocron.dev/projects/cli/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theholocron.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"iamnewton","patreon":"iamnewton"}},"created_at":"2024-10-30T03:31:38.000Z","updated_at":"2025-12-22T19:11:16.000Z","dependencies_parsed_at":"2024-12-16T20:36:49.377Z","dependency_job_id":"daaaa9b7-654a-44dd-bf15-af572d6f0146","html_url":"https://github.com/theholocron/holocron","commit_stats":null,"previous_names":["theholocron/holocron"],"tags_count":1,"template":false,"template_full_name":"theholocron/cli-template","purl":"pkg:github/theholocron/holocron","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theholocron%2Fholocron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theholocron%2Fholocron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theholocron%2Fholocron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theholocron%2Fholocron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theholocron","download_url":"https://codeload.github.com/theholocron/holocron/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theholocron%2Fholocron/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35020872,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"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":["bootstrap","command-line","holocron","nodejs","typescript"],"created_at":"2024-12-05T06:08:34.338Z","updated_at":"2026-07-01T20:00:54.465Z","avatar_url":"https://github.com/theholocron.png","language":"TypeScript","funding_links":["https://github.com/sponsors/iamnewton","https://patreon.com/iamnewton"],"categories":[],"sub_categories":[],"readme":"# Holocron\n\nA pluggable, capability-based CLI for spinning up and operating\nsoftware projects — your own infrastructure-as-tool.\n\n\u003e **Status:** `v2.0.0-alpha.0` — [release notes](https://github.com/theholocron/holocron/releases/tag/v2.0.0-alpha.0).\n\u003e Published under the `alpha` dist-tag on npm. APIs, config shape,\n\u003e and CLI surface may shift before stable v2.0.0. The v1.0.0 line at\n\u003e `@theholocron/cli` (a project-bootstrap CLI) is preserved as an\n\u003e archive under the `v1.0.0` git tag. Design in\n\u003e [`.notes/tech-architecture.spec.md`](./.notes/tech-architecture.spec.md)\n\u003e (tracked in [#74](https://github.com/theholocron/holocron/issues/74)).\n\n## Quickstart\n\n```bash\n# 1. Install the CLI + the two plugins you'll always need\nnpm  i -g @theholocron/cli@alpha\npnpm add -D @theholocron/holocron-plugin-github@alpha \\\n\t\t\t@theholocron/holocron-plugin-1password@alpha\n```\n\n```jsonc\n// 2. Drop a minimal holocron.config.json at your repo root\n{\n\t\"project\": { \"name\": \"my-app\" },\n\t\"providers\": {\n\t\t\"source\": \"github\",\n\t\t\"vault\": [\"1password\", { \"vault\": \"my-app\" }],\n\t},\n}\n```\n\n```bash\n# 3. Verify the wiring\nexport HOLOCRON_GH_TOKEN=ghp_...          # or use --token / a fine-grained PAT\nholocron doctor\n```\n\nEvery additional capability (`ci`, `secrets`, `deployment`, `storage`,\n`auth`, …) is one plugin install + one line of config away. The rest\nof this README is the full picture.\n\n## The idea\n\nMany projects share the same setup work: pick a hosting provider, a\ndatabase, an auth provider, a secret vault, a CI host. Wire all the\nsecrets, the workflows, the deploys, the issue tracker. Holocron\nmakes that work **declarative, swappable, and re-runnable**.\n\n```jsonc\n// holocron.config.json\n{\n\t\"project\": { \"name\": \"my-app\" },\n\n\t\"providers\": {\n\t\t// Code + CI\n\t\t\"source\": \"github\",\n\t\t\"ci\": \"github\",\n\t\t\"secrets\": \"github\",\n\t\t\"environments\": \"github\",\n\t\t\"issues\": \"github\",\n\n\t\t// Hosting + data\n\t\t\"deployment\": [\"vercel\", { \"team\": \"my-team\" }],\n\t\t\"storage\": [\"neon\", { \"kind\": \"postgres\" }],\n\t\t\"auth\": \"clerk\",\n\t\t\"dns\": \"cloudflare\",\n\n\t\t// Source of truth for secrets (required)\n\t\t\"vault\": [\"1password\", { \"vault\": \"my-app\" }],\n\n\t\t// Multi-provider\n\t\t\"tooling\": [\"postman\", \"storybook\"],\n\t\t\"notifications\": [\"slack\", \"discord\"],\n\t\t\"analytics\": [\"google\"],\n\t\t\"observability\": [\"sentry\"],\n\t},\n}\n```\n\nThen:\n\n```bash\nholocron setup           # apply the whole config, top to bottom\nholocron doctor          # check everything's wired right\nholocron secrets sync    # vault → secrets + deployment env vars + .env\nholocron deploy          # ship to your `deployment` provider\n```\n\n## How it works\n\n- **Capabilities** are the contracts (14 of them — see the\n\t[architecture spec](./.notes/tech-architecture.spec.md)).\n- **Plugins** are npm packages named `holocron-plugin-\u003cprovider\u003e`\n\t(or `@theholocron/holocron-plugin-\u003cprovider\u003e` for the built-in\n\tset). Each plugin exports the capabilities it implements — a\n\tsingle provider can cover several (GitHub does source + CI +\n\tissues + secrets + environments).\n- **Config** is ESLint-style: short form `\"vercel\"` for defaults,\n\ttuple form `[\"vercel\", { team: \"my-team\" }]` for options,\n\tmulti-list `[\"slack\", \"discord\"]` for capabilities that allow\n\tseveral providers active at once.\n\n## The vault is special\n\nEvery project has secrets somewhere. They don't go in the repo, they\ndon't go in the config — they go in the **vault**, which is the only\nrequired capability. Everything else that needs secrets (CI, runtime\nenv vars, local `.env`) syncs FROM the vault:\n\n```\nvault (1Password)\n\t├─→ secrets       (GitHub Actions)\n\t├─→ deployment    (Vercel env vars)\n\t└─→ local .env    (for dev)\n```\n\n## Repo layout (v2)\n\n```\npackages/\n\tcli/                            — @theholocron/cli                       (binary + capability runtime)\n\tcli-utils/                      — @theholocron/cli-utils                 (prompts, openers, shell helpers — private; v1 carryover)\n\tholocron-plugin-github/         — @theholocron/holocron-plugin-github    (source, ci, secrets, environments, issues)\n\tholocron-plugin-vercel/         — @theholocron/holocron-plugin-vercel    (deployment)\n\tholocron-plugin-neon/           — @theholocron/holocron-plugin-neon      (storage)\n\tholocron-plugin-clerk/          — @theholocron/holocron-plugin-clerk     (auth)\n\tholocron-plugin-1password/      — @theholocron/holocron-plugin-1password (vault)\n\tholocron-plugin-postman/        — @theholocron/holocron-plugin-postman   (tooling)\nholocron.config.json              — this repo's own holocron config (self-hosted)\n.notes/                           — design specs (draft → proposed → approved)\n.claude/skills/holocron-plugin.md — scaffolding skill for new plugins\n```\n\n## Self-hosting\n\nThis repo carries its own `holocron.config.json` so holocron commands\nwork inside it, and publishes its own packages via npm Trusted\nPublishing (OIDC — no stored `NPM_TOKEN`). Setup + new-package\nbootstrap live in [`docs/self-hosting.md`](./docs/self-hosting.md).\n\n## License\n\nMIT. See [`LICENSE`](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheholocron%2Fholocron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheholocron%2Fholocron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheholocron%2Fholocron/lists"}