{"id":13467679,"url":"https://github.com/charmbracelet/charm","last_synced_at":"2025-03-11T18:17:20.780Z","repository":{"id":37055728,"uuid":"236106066","full_name":"charmbracelet/charm","owner":"charmbracelet","description":"The Charm Tool and Library 🌟","archived":false,"fork":false,"pushed_at":"2025-03-03T10:33:34.000Z","size":1872,"stargazers_count":2435,"open_issues_count":5,"forks_count":78,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-03-04T17:08:16.669Z","etag":null,"topics":["go","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/charmbracelet.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":"2020-01-25T00:23:38.000Z","updated_at":"2025-03-02T11:58:59.000Z","dependencies_parsed_at":"2024-01-07T05:59:58.762Z","dependency_job_id":"eb5f200d-7359-49be-86a9-8733aef31ecb","html_url":"https://github.com/charmbracelet/charm","commit_stats":{"total_commits":711,"total_committers":19,"mean_commits":"37.421052631578945","dds":0.5119549929676512,"last_synced_commit":"6eee9bc5a683244a76adafe24d604ed4634b51f6"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charmbracelet%2Fcharm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charmbracelet%2Fcharm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charmbracelet%2Fcharm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charmbracelet%2Fcharm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/charmbracelet","download_url":"https://codeload.github.com/charmbracelet/charm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243086247,"owners_count":20234005,"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","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":["go","golang"],"created_at":"2024-07-31T15:00:59.242Z","updated_at":"2025-03-11T18:17:20.754Z","avatar_url":"https://github.com/charmbracelet.png","language":"Go","funding_links":[],"categories":["Go","Cross-Platform Time Tracking","Applications"],"sub_categories":["Development Tools"],"readme":"# Sunsetting Charm Cloud\n\nTo continue innovating in this space and supporting our larger projects, we need to keep our team focused on the most impactful work. On **29 November 2024**, we sunset Charm Cloud.\n\nThe code will continue to be open source and publicly available. If you love this project and would like to maintain a fork, please do.\n\n[Learn more](https://github.com/charmbracelet/charm/blob/main/docs/self-hosting.md) about self-hosting Charm Cloud.\n\n## Impacted tools\n\nTo configure both [Skate](https://github.com/charmbracelet/skate) and [Glow](https://github.com/charmbracelet/glow) to work with your own server, you'll need to update the Charm Cloud client environment variables. Glow historically integrated into the Charm Cloud via a stashing feature, but as of [Skate v1.0.0][skatev1] and [Glow v2.0.0][glowv2] the Charm Cloud integration in both applications has been removed (Skate now operates on a local database: to migrate your data see the [Skate v1.0.0 Release Notes][skatev1]). For those using older versions, you can continue to use Charm Cloud features with your own server. Here are the relevant environment variables:\n\n```go\n// Config contains the Charm client configuration.\ntype Config struct {\n  Host        string `env:\"CHARM_HOST\" envDefault:\"cloud.charm.sh\"`\n  SSHPort     int    `env:\"CHARM_SSH_PORT\" envDefault:\"35353\"`\n  HTTPPort    int    `env:\"CHARM_HTTP_PORT\" envDefault:\"35354\"`\n  Debug       bool   `env:\"CHARM_DEBUG\" envDefault:\"false\"`\n  Logfile     string `env:\"CHARM_LOGFILE\" envDefault:\"\"`\n  KeyType     string `env:\"CHARM_KEY_TYPE\" envDefault:\"ed25519\"`\n  DataDir     string `env:\"CHARM_DATA_DIR\" envDefault:\"\"`\n  IdentityKey string `env:\"CHARM_IDENTITY_KEY\" envDefault:\"\"`\n}\n```\nSource: [https://github.com/charmbracelet/charm/blob/main/client/client.go](https://github.com/charmbracelet/charm/blob/main/client/client.go#L28-L37)\n\nThanks for using the Charm Cloud and please chat us up in [Discord](https://charm.sh/chat) if you have any questions.\n\n[glowv2]: https://github.com/charmbracelet/glow/releases/tag/v2.0.0\n[skatev1]: https://github.com/charmbracelet/skate/releases/tag/v1.0.0\n\n***\n\nCharm\n=====\n\n\u003cp\u003e\n  \u003cimg src=\"https://stuff.charm.sh/charm/charm-header.png?14\" width=\"220\" alt=\"A little cloud with a pleased expression followed by the words ‘Charm from Charm’\"\u003e\u003cbr\u003e\n  \u003ca href=\"https://github.com/charmbracelet/charm/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/release/charmbracelet/charm.svg\" alt=\"Latest Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pkg.go.dev/github.com/charmbracelet/charm?tab=doc\"\u003e\u003cimg src=\"https://godoc.org/github.com/golang/gddo?status.svg\" alt=\"GoDoc\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/charmbracelet/charm/actions\"\u003e\u003cimg src=\"https://github.com/charmbracelet/charm/workflows/build/badge.svg\" alt=\"Build Status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://nightly.link/charmbracelet/charm/workflows/nightly/main\"\u003e\u003cimg src=\"https://shields.io/badge/-Nightly%20Builds-orange?logo=hackthebox\u0026logoColor=fff\u0026style=appveyor\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nCharm is a set of tools that makes adding a backend to your terminal-based\napplications fun and easy. Quickly build modern CLI applications without\nworrying about user accounts, data storage and encryption.\n\n## Features\n\n* [**Charm KV:**](#charm-kv) an embeddable, encrypted, cloud-synced key-value store built on [BadgerDB][badger]\n* [**Charm FS:**](#charm-fs) a Go `fs.FS` compatible cloud-based user filesystem\n* [**Charm Crypt:**](#charm-crypt) end-to-end encryption for stored data and on-demand encryption for arbitrary data\n* [**Charm Accounts:**](#charm-accounts) invisible user account creation and authentication\n\nThere’s also the powerful [Charm Client](#charm-client) for directly accessing\nCharm services. [Self-hosting](#self-hosting) a Charm Cloud is as simple as\nrunning `charm serve`.\n\n## Installation\n\nUse a package manager:\n\n```bash\n# macOS or Linux\nbrew install charmbracelet/tap/charm\n\n# Arch Linux (btw)\npacman -S charm\n\n# Nix\nnix-env -iA nixpkgs.charm\n\n# Debian/Ubuntu\nsudo mkdir -p /etc/apt/keyrings\ncurl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg\necho \"deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *\" | sudo tee /etc/apt/sources.list.d/charm.list\nsudo apt update \u0026\u0026 sudo apt install charm\n\n# Fedora/RHEL\necho '[charm]\nname=Charm\nbaseurl=https://repo.charm.sh/yum/\nenabled=1\ngpgcheck=1\ngpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo\nsudo yum install charm\n```\n\nOr download a package or binary from the [releases][releases] page. All\nmajor platforms and architectures are supported, including FreeBSD and ARM.\n\nYou can also just build and install it yourself:\n\n```bash\ngit clone https://github.com/charmbracelet/charm.git\ncd charm\ngo install\n```\n\n## Charm KV\n\nA powerful, embeddable key-value store built on [BadgerDB][badger]. Store user\ndata, configuration, create a cache or even store large files as values.\n\nWhen you use Charm KV your users automatically get cloud backup, multi-machine\nsyncing, end-to-end encryption, and the option to self-host.\n\n```go\nimport \"github.com/charmbracelet/charm/kv\"\n\n// Open a database (or create one if it doesn’t exist)\ndb, err := kv.OpenWithDefaults(\"my-cute-db\")\nif err != nil {\n    log.Fatal(err)\n}\ndefer db.Close()\n\n// Fetch updates and easily define your own syncing strategy\nif err := db.Sync(); err != nil {\n    log.Fatal(err)\n}\n\n// Save some data\nif err := db.Set([]byte(\"fave-food\"), []byte(\"gherkin\")); err != nil {\n    log.Fatal(err)\n}\n\n// All data is binary\nif err := db.Set([]byte(\"profile-pic\"), someJPEG); err != nil {\n    log.Fatal(err)\n}\n```\n\nCharm KV can also enhance existing [BadgerDB][badger] implementations. It works\nwith standard Badger transactions and provides top level functions that mirror\nthose in Badger.\n\nFor details on Charm KV, see [the Charm KV docs][kv].\n\n## Charm FS\n\nEach Charm user has a virtual personal filesystem on the Charm server. Charm\nFS provides a Go [fs.FS](https://golang.org/pkg/io/fs/) implementation for the\nuser along with additional write and delete methods. If you're building\na tool that requires file storage, Charm FS will provide it on\na networked-basis without friction-filled authentication flows.\n\n```go\nimport charmfs \"github.com/charmbracelet/charm/fs\"\n\n// Open the user’s filesystem\ncfs, err := charmfs.NewFS()\nif err != nil {\n    log.Fatal(err)\n}\n\n// Save a file\ndata := bytes.NewBuffer([]byte(\"some data\"))\nif err := cfs.WriteFile(\"./path/to/file\", data, fs.FileMode(0644), int64(data.Len())); err != nil {\n    log.Fatal(err)\n}\n\n// Get a file\nf, err := cfs.Open(\"./path/to/file\")\nif err != nil {\n    log.Fatal(err)\n}\ndefer f.Close()\n\n// Just read whole file in one shot\ndata, err := cfs.ReadFile(\"./path/to/file\")\nif err != nil {\n    log.Fatal(err)\n}\n```\n\n### FAQ\n\n\u003cdetails\u003e\n\t\u003csummary\u003eAre there any file size limits?\u003c/summary\u003e\n\t\u003cp\u003eThere are no limitations in file size per se, although there's a 1 GB cap on storage for the free Charm accounts, but you can get unlimited if you self-host the Charm Cloud.\u003c/p\u003e\n\u003c/details\u003e\n\u003cdetails\u003e\n\t\u003csummary\u003eIs it possible to not have a local copy of the database?\u003c/summary\u003e\n\t\u003cp\u003eNo. Skate uses BadgerDB and keeps a local copy of the key-value store. The local databases are synced through the Charm Cloud.\u003c/p\u003e\n\u003c/details\u003e\n\nFor more on Charm FS see [the Charm FS docs][fs].\n\n## Charm Crypt\n\nAll data sent to a Charm server is fully encrypted on the client. Charm Crypt\nprovides methods for easily encrypting and decrypting data for a Charm user.\nAll key management and account linking is handled seamlessly by Charm.\n\nFor more on Charm Crypt see [the Charm Crypt docs][crypt].\n\n## Charm Accounts\n\nThe best part of Charm accounts is that both you and your users don’t need to\nthink about them. Charm authentication is based on SSH keys, so account\ncreation and authentication is built into all Charm tools and is invisible and\nfrictionless.\n\nIf a user already has Charm keys, we authenticate with them. If not, we create\nnew ones. Users can also easily link multiple machines to their account, and\nlinked machines will seamlessly gain access to their owners Charm data. Of\ncourse, users can revoke machines’ access too.\n\n### Backups\n\nYou can use `charm backup-keys` to backup your account keys. Your account can\nbe recovered using `charm import-keys charm-keys-backup.tar`\n\n## Charm Client\n\nThe [`charm`][releases] binary also includes easy access to a lot of the functionality\navailable in the libraries. This could be useful in scripts, as a standalone\nutility or when testing functionality.\n\n```bash\n# Link a machine to your Charm account\ncharm link\n\n# Set a value\ncharm kv set weather humid\n\n# Print out a tree of your files\ncharm fs tree /\n\n# Encrypt something\ncharm crypt encrypt \u003c secretphoto.jpg \u003e encrypted.jpg.json\n\n# For more info\ncharm help\n```\n\n### Client Settings\n\nThe Charm client can be configured using environment variables. These are the\ndefaults: \n\n* `CHARM_HOST`: Server public URL (_default cloud.charm.sh_)\n* `CHARM_SSH_PORT`: SSH port to connect to (_default 35353_)\n* `CHARM_HTTP_PORT`: HTTP port to connect to (_default 35354_)\n* `CHARM_DEBUG`: Whether debugging logs are enabled (_default false_)\n* `CHARM_LOGFILE`: The file path to output debug logs\n* `CHARM_KEY_TYPE`: The type of key to create for new users (_default ed25519_)\n* `CHARM_DATA_DIR`: The path to where the user data is stored\n* `CHARM_IDENTITY_KEY`: The path to the identity key used for auth\n\n## Self-Hosting\n\nCharm libraries point at our Charmbracelet, Inc. servers by default (that’s\ncloud.charm.sh), however it's very easy for users to host their own Charm\ninstances. The `charm` binary is a single, statically-linked executable capable\nof serving an entire Charm instance:\n\n```bash\ncharm serve\n```\n\n### Server settings\n\nThe Charm server can be configured using environment variables. These are the defaults:\n\n* `CHARM_SERVER_BIND_ADDRESS`: Network interface to listen to (_default 0.0.0.0_)\n* `CHARM_SERVER_HOST`: Hostname to advertise (_default localhost_)\n* `CHARM_SERVER_SSH_PORT`: SSH server port to listen to (_default 35353_)\n* `CHARM_SERVER_HTTP_PORT`: HTTP server port to listen to (_default 35354_)\n* `CHARM_SERVER_STATS_PORT`: Stats server port to listen to (_default 35355_)\n* `CHARM_SERVER_HEALTH_PORT`: Health server port to listen to (_default 35356_)\n* `CHARM_SERVER_DATA_DIR`: Server data directory (_default ./data_)\n* `CHARM_SERVER_USE_TLS`: Whether to use TLS (_default false_)\n* `CHARM_SERVER_TLS_KEY_FILE`: The TLS key file path to use\n* `CHARM_SERVER_TLS_CERT_FILE`: The TLS cert file path to use\n* `CHARM_SERVER_PUBLIC_URL`: Server public URL, useful when hosting the Charm server behind a TLS enabled reverse proxy\n* `CHARM_SERVER_ENABLE_METRICS`: Whether to enable collecting Prometheus metrics (_default false_) Metrics can be accessed from `http://\u003cCHARM_SERVER_HOST\u003e:\u003cCHARM_SERVER_STATS_PORT\u003e/metrics`\n* `CHARM_SERVER_USER_MAX_STORAGE`: Maximum FS storage for a user (_default 0_) Zero means no limit\n\nTo change hosts, users can set `CHARM_HOST` to the domain or IP of their\nchoosing:\n\n```bash\nexport CHARM_HOST=burrito.example.com\n```\n\nSee instructions for\n[Systemd](https://github.com/charmbracelet/charm/blob/main/systemd.md) and\n[Docker](https://github.com/charmbracelet/charm/blob/main/docker.md).\n\n#### Storage Considerations\n\nThe max data you can store on our Charm Cloud servers is 1GB per account.\nBy default, self-hosted servers don't have a data storage limit. Should you\nwant to set a max storage limit on your server, you can do so using\n`CHARM_SERVER_USER_MAX_STORAGE`\n\n### TLS\n\nTo set up TLS, you should set `CHARM_SERVER_USE_TLS` to `true`, and specify\n`CHARM_SERVER_HOST`, `CHARM_SERVER_TLS_KEY_FILE`, and\n`CHARM_SERVER_TLS_CERT_FILE` file paths.\n\n## Projects using Charm\n\n* [Glow][glow]: Render markdown on the CLI, with pizzazz! 💅🏻\n* [Skate][skate]: A personal key-value store 🛼\n* Your app here! [Let us know what you build](https://twitter.com/charmcli)\n\n## Feedback\n\nWe’d love to hear your thoughts on this project. Feel free to drop us a note!\n\n* [Twitter](https://twitter.com/charmcli)\n* [The Fediverse](https://mastodon.technology/@charm)\n* [Slack](https://charm.sh/slack)\n\n## License\n\n[MIT](https://github.com/charmbracelet/charm/raw/main/LICENSE)\n\n***\n\nPart of [Charm](https://charm.sh).\n\n\u003ca href=\"https://charm.sh/\"\u003e\u003cimg alt=\"the Charm logo\" src=\"https://stuff.charm.sh/charm-badge.jpg\" width=\"400\"\u003e\u003c/a\u003e\n\nCharm热爱开源 • Charm loves open source\n\n\n[releases]: https://github.com/charmbracelet/charm/releases\n[docs]: https://pkg.go.dev/github.com/charmbracelet/charm?tab=doc\n[kv]: https://github.com/charmbracelet/charm/tree/main/kv\n[fs]: https://github.com/charmbracelet/charm/tree/main/fs\n[crypt]: https://github.com/charmbracelet/charm/tree/main/crypt\n[glow]: https://github.com/charmbracelet/glow\n[skate]: https://github.com/charmbracelet/skate\n[badger]: https://github.com/dgraph-io/badger\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharmbracelet%2Fcharm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcharmbracelet%2Fcharm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharmbracelet%2Fcharm/lists"}