{"id":15651539,"url":"https://github.com/sinedied/devto-cli","last_synced_at":"2025-05-07T21:40:26.013Z","repository":{"id":38172927,"uuid":"254421184","full_name":"sinedied/devto-cli","owner":"sinedied","description":"Dev.to authoring CLI to create and publish markdown files as articles, using assets hosted on GitHub.","archived":false,"fork":false,"pushed_at":"2024-07-18T09:29:49.000Z","size":2626,"stargazers_count":38,"open_issues_count":6,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-05T05:49:32.887Z","etag":null,"topics":["articles","authoring","cli","dev","github","hacktoberfest","host","markdown","node","publish","sync"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/sinedied.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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-04-09T16:17:22.000Z","updated_at":"2025-03-13T11:17:38.000Z","dependencies_parsed_at":"2024-07-18T11:14:09.715Z","dependency_job_id":"e2274377-a12c-445e-9064-b94111bd0c94","html_url":"https://github.com/sinedied/devto-cli","commit_stats":{"total_commits":167,"total_committers":3,"mean_commits":"55.666666666666664","dds":0.07185628742514971,"last_synced_commit":"a855ab374138e73d6e7559e664bb2cccf65bb421"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinedied%2Fdevto-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinedied%2Fdevto-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinedied%2Fdevto-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinedied%2Fdevto-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sinedied","download_url":"https://codeload.github.com/sinedied/devto-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252961080,"owners_count":21832179,"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":["articles","authoring","cli","dev","github","hacktoberfest","host","markdown","node","publish","sync"],"created_at":"2024-10-03T12:38:55.978Z","updated_at":"2025-05-07T21:40:25.986Z","avatar_url":"https://github.com/sinedied.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# :postbox: devto-cli\n\n[![NPM version](https://img.shields.io/npm/v/@sinedied/devto-cli.svg)](https://www.npmjs.com/package/@sinedied/devto-cli)\n[![Build Status](https://github.com/sinedied/devto-cli/workflows/build/badge.svg)](https://github.com/sinedied/devto-cli/actions)\n![Node version](https://img.shields.io/node/v/@sinedied/devto-cli.svg)\n[![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/593151/82310296-7c85ba80-99c4-11ea-88c2-8e6452885e6a.png\" alt=\"cli logo\" width=\"160px\"\u003e\n\u003c/p\u003e\n\n\u003e [Dev.to](https://dev.to) authoring CLI to create and publish markdown files as articles, using assets hosted on GitHub.\n\n#### Main features\n- Create \u0026 update dev.to articles based on markdown files\n- Quickly bootstrap a GitHub repository ready to synchronize with dev.to\n- Create new articles with front matter ready\n- Show stats for your latest published articles\n- No config file needed 😎\n\n#### What's dev.to?\n\n\u003e https://dev.to is a free and open source content platform for developers. It's also an excellent way to engage with developer community, discuss about tech and a welcoming place for beginners.\n\n## Installation\n\n`npm install -g @sinedied/devto-cli`\n\nIf you only want to synchronize a GitHub repository with dev.to, you can follow this [quickstart tutorial](#create-a-new-github-repository-synchronized-with-devto) without installing the CLI.\n\n## Usage\n\n```\nUsage: dev \u003cinit|new|push|stats\u003e [options]\n\nCommands:\n  i, init               Init current dir as an article repository\n    -p, --pull          Pull your articles from dev.to\n    -s, --skip-git      Skip git repository init\n  n, new \u003cfile\u003e         Create new article\n  p, push [files]       Push articles to dev.to [default: posts/**/*.md]\n    -d, --dry-run       Do not make actual changes on dev.to\n    -e, --reconcile     Reconcile articles without id using their title\n  s, stats              Display stats for your latest published articles\n    -n, --number \u003cn\u003e    Number of articles to list stats for [default: 10]\n    -j, --json          Format result as JSON\n\nGeneral options:\n  -t, --token \u003ctoken\u003e   Use this dev.to API token\n  -r, --repo \u003crepo\u003e     GitHub repository (in \"user/repo\" form)\n  -b, --branch \u003cbranch\u003e GitHub branch [default: master]\n  -v, --version         Show version\n  --verbose             Show detailed logs\n  --help                Show this help\n```\n\n### Init\n\n`dev init` initializes the current folder as a repository for all your articles.\n\nIt does 3 things:\n\n1. Setup a [GitHub Actions workflow](https://github.com/sinedied/publish-devto) to automatically push your updates to dev.to each time a new commit is added to the `main` branch.\n\n2. Create a `posts` folder with a first article\n\n3. Make the current folder a git repository, unless the `--skip-git` option is used. [Git](https://git-scm.com) must be installed otherwise this step will be skipped.\n\nThere are a few more step needed to finish the setup on GitHub, see the [quickstart tutorial](#create-a-new-github-repository-synchronized-with-dev.to) for details.\n\n### New\n\n`dev new \u003cfile\u003e` creates a new markdown file with front matter properties prepared for you.\n\n### Push\n\n`dev push [files]` pushes all updates for the specified files to dev.to (`posts/***/*.md` by default, globs supported).\n\nThis command only updates articles that have changes.\n\nIf an article have an `id` property defined in front matter it will be updated, otherwise a new article will be created and the local file will be updated with the `id`. You can also [reconcile articles](#reconcile-with-existing-articles) without an `id` property using their title if needed.\n\nWhen an article is pushed with `published: true`, a new property `date` will be added to the local file to recird the article's publication date.\n\n### Images hosting\n\nYou can add image files in your repository along your markdown and link to them directly. \n\nWhen an article is pushed to dev.to, all **relative** images links (without an `http(s)://` prefix) will be modified with the format `https://raw.githubusercontent.com/\u003cUSER\u003e/\u003cREPO_NAME\u003e/\u003cBRANCH\u003e/` prefix to leverage GitHub hosting. You have make sure that you pushed your git changes including the images to your GitHub repository, otherwise you might end up with `404` errors. By default the CLI will [check]((#check-for-offline-images)) that all your linked images are online before pushing to avoid mistakes.\n\nAll absolute image links will be left untouched, so you can choose to host your images elsewhere if you prefer.\n\n#### Reconcile with existing articles\n\nIf you have markdown files for articles that are already on dev.to but do not have an `id` front matter property, you can use `--reconcile` option to match articles using their title, to avoid duplicates.\n\nMatched local files will then be updated with the corresponding `id` property.\n\nYou can use [dry run](#dry-run) mode to ensure that your articles properly match without making any changes.\n\n#### Check for offline images\n\nBy default thee CLI will check all images URLs of an article to be online before pushing the changes to dev.to.\n\nIf an image is offline, the article will be marked as failed and won't be pushed to dev.to. You can use the `--verbose` option to see which image was found offline.\n\nThis is particularly useful as dev.to cache images for quite a long time, including URLs resulting in 404 errors. This means that even if you fix your image after seeing it broken, dev.to will still show a broken image until the cache is expired.\n\nYou can disable this behavior using the `--skip-check-images` option, but it's really not recommended to do so.\n\n#### Dry run\n\nUsing the `--dry-run` option the whole push process will be executed, but without making any changes on dev.to or local files. You can use this to check your configuration and see what changes you can expect.\n\n### Stats\n\n`dev stats` allows you to see the stats for your latest *published* articles.\n\nOnly the latest 10 are shown by default, but you can change that number using the `--number` option.\n\nYou can also choose to get the resultats formatted as JSON using the `--json` options.\n\n### Configure dev.to token and GitHub repository URL and branch\n\nMost commands require a [dev.to API key](https://docs.dev.to/api/#section/Authentication/api_key) and a GitHub repository url and branch to work properly.\n\n#### Dev.to token\n\nFirst, if you don't have a dev.to API key you have to generate one following [this procedure](https://developers.forem.com/api/#section/Authentication/api_key).\n\nYou can either use the `--token` to provide the token to CLI commands, or set the `DEVTO_TOKEN` environment variable.\n\nAs an alternative, you can also create a `.env` file at the root of your articles repository and add `DEVTO_TOKEN=\u003cYOUR_TOKEN\u003e` in it. BE SURE TO AVOID COMMITTING THAT FILE TO GITHUB, otherwise your token will be exposed.\n\n#### GitHub repository URL and branch\n\nIn order to [host your images using GitHub](#images-hosting) the tool needs to know your GitHub repository URL and branch.\n\nIf your git repository is initialized and you have the `origin` remote set to your GitHub repository it will be auto-detected and you have nothing to do.\n\nOtherwise, you can either use the `--repo` option to provide your GitHub repository in the form `\u003cUSER\u003e/\u003cREPO_NAME\u003e`, or set the `DEVTO_REPO` environment variable.\n\nYou can also create a `.env` file at the root of your repository and add `DEVTO_REPO=\u003cUSER\u003e/\u003cREPO_NAME\u003e` in it.\n\nBy default, the tool will try to detect the branch from which it was run and use it. If you want to use a different branch, you can use the `--branch` option to specify it, or set the `DEVTO_BRANCH` environment variable.\n\nYou can also add `DEVTO_REPO=\u003cBRANCH\u003e` in a `.env` file at the root of your repository.\n\n## Using frontmatter properties\n\nAny markdown file matching the specified input pattern and containing at least a `title` frontmatter property will be considered as an article and synchronized with dev.to.\n\nAll frontmatter properties [natively supported by dev.to](https://dev.to/p/editor_guide#front-matter) can be used here.\n\nIn addition, these frontmatter properties specified to the CLI are used to configure the behavior of the tool:\n- `id`: The article ID on dev.to. If not specified, a new article will be created on publish.\n- `date`: The publication date of the article. If not specified, the current date will be used on publish.\n- `devto_sync`: If set to `false`, the article will not be synchronized with dev.to at all.\n\n## Create a new GitHub repository synchronized with dev.to\n\nThe easiest way to get started is to:\n\n1. Create a new GitHub repository using [this template](https://github.com/sinedied/devto-github-template/generate)\n\n1. Go to https://developers.forem.com/api/#section/Authentication/api_key and follow the **Getting an API key** instructions to generate your own dev.to API key.\n\n1. Select the **Settings** tab on your GitHub repository, then go to the **Secrets** section.\n\n1. Add a secret called **DEVTO_TOKEN** with the value of your dev.to API key.\n\nNow your articles are ready to be published on dev.to! 🎉\n\n### Starting from scratch\n\nAlternatively, instead of using the template, you can start from scratch with the CLI.\n\n1. Create a new folder on your machine, the use the `dev init` command to initialize the files.\n\n1. Commit the changes: `git add . \u0026\u0026 git commit -m \"feat: add dev.to workflow\"`\n\n1. Create a new repository on GitHub, and follow the instructions to push an existing repository, that was created by `dev init`.\n\n1. Go to https://developers.forem.com/api/#section/Authentication/api_key and follow the **Getting an API key** instructions to generate your own dev.to API key.\n\n1. Select the **Settings** tab on your GitHub repository, then go to the **Secrets** section.\n\n1. Add a secret called **DEVTO_TOKEN** with the value of your dev.to API key.\n\n## Related\n\nThis CLI was heavily inspired by the [dev-to-git](https://github.com/maxime1992/dev-to-git). I used in fact `dev-to-git` for some time, but ultimately wanted something more flexible and easier to use and setup without the need for config files. I also wanted full automation support in a GitHub Action, leading me to create this new tool.\n\nThe [publish-devto](https://github.com/sinedied/publish-devto) GitHub action use this CLI under the hood to provide a single step dev.to publish workflow with GitHub Actions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinedied%2Fdevto-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsinedied%2Fdevto-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinedied%2Fdevto-cli/lists"}