{"id":17584726,"url":"https://github.com/cssmagic/kup","last_synced_at":"2026-05-03T18:09:58.356Z","repository":{"id":39605419,"uuid":"491373351","full_name":"cssmagic/kup","owner":"cssmagic","description":"A CLI tool to sync local Markdown files to GitHub issues.","archived":false,"fork":false,"pushed_at":"2024-09-11T03:45:08.000Z","size":30,"stargazers_count":7,"open_issues_count":11,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-19T08:14:34.890Z","etag":null,"topics":["cli","github-issue","markdown"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/cssmagic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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-12T05:16:01.000Z","updated_at":"2025-02-01T18:58:57.000Z","dependencies_parsed_at":"2024-10-22T23:03:02.022Z","dependency_job_id":null,"html_url":"https://github.com/cssmagic/kup","commit_stats":{"total_commits":23,"total_committers":1,"mean_commits":23.0,"dds":0.0,"last_synced_commit":"9ffe9890f054d893036cc4a16b46365016dca1fa"},"previous_names":["cssmagic/tou"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cssmagic%2Fkup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cssmagic%2Fkup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cssmagic%2Fkup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cssmagic%2Fkup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cssmagic","download_url":"https://codeload.github.com/cssmagic/kup/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251343148,"owners_count":21574314,"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":["cli","github-issue","markdown"],"created_at":"2024-10-22T02:07:53.363Z","updated_at":"2026-05-03T18:09:58.351Z","avatar_url":"https://github.com/cssmagic.png","language":"JavaScript","funding_links":[],"categories":["工具"],"sub_categories":[],"readme":"English | [中文](README.zh.md)\n\n# Kup\n\n\u003cimg src=\"https://user-images.githubusercontent.com/1231359/171321963-e8e73bdf-f9c8-435b-9707-318e92f1805a.png\" width=\"150\" height=\"80\" align=\"right\" alt=\"Kup logo\"\u003e\n\n\u003e A CLI tool to sync local Markdown files and GitHub issues bidirectionally.\n\u003e\n\u003e 一款命令行工具，实现本地 Markdown 文件与 GitHub Issues 的双向同步。\n\n\n\n## Who Is It For\n\n* Bloggers who publish with GitHub issues and want to edit drafts locally.\n* Open-source authors who publish documentation through GitHub issues.\n* Anyone else who needs to update GitHub issues frequently.\n\n\n\n## Installation\n\n```sh\nnpm install -g kup-cli\n```\n\nInstall it globally so you can use it anytime, anywhere from the command line. (When a new version of Kup is released, run the same command again to upgrade.)\n\n\n\n## Usage\n\n### Publish a New Issue\n\n```sh\nkup ./path/to/file.md --repo foo/bar\n```\n\nKup will publish the content of `file.md` as a new issue in the `foo/bar` repository, and report the new issue number after it succeeds.\n\n### Update an Existing Issue\n\n```sh\nkup ./path/to/file.md --repo foo/bar --id 123\n```\n\nKup will update issue `123` in the `foo/bar` repository with the content of `file.md`.\n\n### Dump an Existing Issue\n\n```sh\nkup --dump --repo foo/bar --id 123\n```\n\nKup will dump issue `123` from the `foo/bar` repository to `123.md` in the current directory.\n\nIf you want to specify the output file, you can also use:\n\n```sh\nkup ./path/to/file.md --dump --repo foo/bar --id 123\n```\n\n### Preparation\n\nUpdating GitHub issues requires authentication, so you need to provide a GitHub token for Kup to call the GitHub API.\n\n1. Create a new token on GitHub's \"[Personal access tokens](https://github.com/settings/tokens)\" page, and make sure the `repo` scope is selected. (See [this document](https://github.com/cssmagic/kup/issues/17) for details.)\n\n2. Put the token into an environment variable:\n\n   ```sh\n   export GITHUB_TOKEN=ghp_**********\n   ```\n\nIf Kup cannot read a token from the environment, it will prompt you for one in the terminal.\n\n\n\n## Command-Line Options\n\nOption | Short | Value Type | Description\n---|---|---|---\n`--repo` | `-r` | string | Specify the GitHub repository\n`--id` | `-i` | integer | Specify the issue number: \u003cul\u003e\u003cli\u003eProviding a number means updating an existing issue\u003cli\u003eOmitting it means publishing a new issue\u003c/ul\u003e\n`--dump` | `-d` | - | Enable dump mode, save a GitHub issue as a local Markdown file\n`--version` | `-v` | - | Show the version number\n`--help` | `-h` | - | Show help information\n\n\n\n\u0026nbsp;\n\n\u003e ***\n\u003e\n\u003e ### **🙋‍♂️ Open to Work (Remote, Global)**\n\u003e\n\u003e * Senior Fullstack Engineer · Node.js, React, Vue, TS · 10+ years\n\u003e * Published author on “AI Coding” · GitHub 3k+ followers\n\u003e * → Resume / Contact: https://github.com/cssmagic/cssmagic\n\u003e\n\u003e ***\n\n\u0026nbsp;\n\n\n\n## Advanced\n\n### How can I specify the `repo` option more conveniently?\n\nKup can determine the `repo` option in the following order of priority:\n\n1. The `--repo` option passed on the command line.\n1. The `repo` field in the Markdown file's [metadata](https://github.com/cssmagic/kup/issues/1).\n1. The `kup.repo` field in the current project's `package.json`. Kup starts from the Markdown file's directory and searches upward for a `package.json` file.\n1. If `kup.repo` is not present in `package.json`, Kup will try to infer the repository name from the `repository` field and ask for confirmation before using it.\n1. If that still fails, Kup will continue searching for `.git/config` in the current or parent directories, then try to infer the repository name from the `url` field of `remote \"origin\"` and ask for confirmation before using it.\n\nIf the entire project syncs to the same repository, it is usually best to configure `kup.repo` in `package.json`.\n\n### How can I specify the `id` option more conveniently?\n\nKup can determine the `id` option in the following order of priority:\n\n1. The `--id` option passed on the command line.\n1. The `id` field in the Markdown file's metadata.\n\nAfter a file is successfully published as an issue, Kup writes the `id` back to the file’s metadata (with user confirmation before writing).\n\n### How is the issue title determined?\n\nKup determines the issue title using the following hints, in descending priority:\n\n1. The `title` field in the Markdown file's metadata.\n1. If the first Markdown block is an H1 heading (in `# Title` form), Kup uses its text as the title. In this case, that H1 heading is excluded from the synced content.\n\nWhat happens if Kup still cannot determine the issue title?\n\n* When publishing a new issue, Kup generates a title automatically.\n* When updating an existing issue, Kup ignores the title, which means the existing title will not be changed.\n\n### How do I assign labels to an issue?\n\nWhether you are blogging or publishing regular issues, labels are often useful, so Kup supports them as well.\n\nAdd a `tags` field to the Markdown file's metadata and specify one or more labels. These labels do not need to exist in the GitHub repository beforehand. If a label does not already exist, it will be created automatically when the issue is published.\n\nWhat happens if there is no `tags` field in the metadata?\n\n* When publishing a new issue, Kup will not assign any labels.\n* When updating an existing issue, Kup ignores labels, which means the existing labels will not be changed.\n\nWhen updating an existing issue, if the labels specified in the metadata differ from the issue's current labels, the new set completely replaces the old one.\n\n### How do I specify a proxy?\n\nUse the `https_proxy` environment variable to specify a proxy. Kup will use this proxy when making requests to the GitHub API.\n\n\n\n## Documentation\n\n* [Metadata examples for Markdown files](https://github.com/cssmagic/kup/issues/1)\n* [How to generate an appropriate GitHub token for Kup](https://github.com/cssmagic/kup/issues/17)\n\n\n\n## Other\n\n### Roadmap\n\n* See [the issue list for this project](https://github.com/cssmagic/kup/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) for current plans.\n* Feature requests and RFC discussions are welcome.\n\n### About the Name\n\n* Kup comes from the English word \"pickup\", suggesting lightweight transport.\n* Kup is also a character in *Transformers*.\n\n### About the Logo\n\n* The logo was created by [Fasil](https://freeicons.io/profile/722) and provided for free via [freeicons.io](https://freeicons.io/icon/e-commerce-icons/pickup-truck-icon-26893).\n\n***\n\n## License\n\n\u003e Any code contributed to this project is considered authorized for commercial use by the project authors and their affiliated companies and distributed under this project's license.\n\u003e\n\u003e 任何贡献到本项目的代码，均视为授权本项目作者及其关联公司用于商业用途，并可按本项目协议进行分发。\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcssmagic%2Fkup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcssmagic%2Fkup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcssmagic%2Fkup/lists"}