# Introducing DevPub - Open Source Dev.to CLI Tool

> Source: <https://dev.to/sarvar_04/introducing-devpub-open-source-devto-cli-tool-49jf>
> Published: 2026-08-01 12:10:00+00:00

Recently I went looking for a CLI tool to manage my Dev.to articles from the terminal. I write 4-5 articles per month, track analytics obsessively, and wanted a git-backed workflow.

I found 9 existing tools. Tried them all. Here's what happened:

Every single tool does the same thing: publish an article. That's it. Maybe pull. Maybe validate tags.

Meanwhile the Dev.to API has **40+ endpoints** including analytics, semantic search, ML-powered content concepts, follower engagement, trend tracking, and reading list management. Nobody uses them.

So I built ** devpub**.

```
# The basics (every tool does this)
devpub push -f articles/my-post.md
devpub pull

# Analytics in your terminal
devpub stats
# Views: 246.5K | Reactions: 4.4K | Comments: 402 | Followers: 18.9K

# Full dashboard with top articles
devpub dashboard

# AI-powered search (semantic, not keyword)
devpub search "building serverless apps" --semantic

# What's trending RIGHT NOW
devpub trends

# Catch problems before publishing
devpub validate
```

The difference isn't one feature. It's coverage. Here's the comparison:

| Capability | devpub | Everyone else |
|---|---|---|
| Publish/update articles | Yes | Yes |
| Pull articles to local | Yes | Some |
| Analytics (7 endpoints) | Yes | No |
| Semantic search | Yes | No |
| Trend discovery | Yes | No |
| Article validation | Yes | No |
| Rate limiting (30 req/30s) | Yes | No |
| Retry logic for failures | Yes | No |
| Concepts API (ML topics) | Yes | No |

While building devpub, I found several API endpoints that aren't documented anywhere obvious:

**1. Semantic Search** -- Dev.to has a full embedding-based search system using Gemini embeddings (768-dimensional vectors) with pgvector. You can search articles by *meaning*, not just keywords. The endpoint returns cosine similarity scores.

**2. Concepts API** -- These are ML-generated topic classifications with daily metrics: page views, reactions, comments, popularity scores. Way more powerful than manual tags.

**3. V1 Accept Header** -- The V1 API requires `Accept: application/vnd.forem.api-v1+json`

. Without it, you get V0 responses. I didn't see this mentioned in any competitor's code.

**4. Nested analytics responses** -- The analytics endpoints return nested objects like `{"page_views": {"total": 246454, "average_read_time_in_seconds": 306}}`

, not flat integers. Every tool I checked either doesn't use analytics or would break on this structure.

I built devpub's core in a day. Started at 2 PM on a Monday, had a working CLI by evening. Here's the honest timeline:

**Hour 1-2: Research**

Before writing a single line of code, I analyzed 9 competing tools. Downloaded them, read their source, mapped which API endpoints each one used. Found that the most "complete" tool covered 12 out of 40+ endpoints. Most covered 3-5.

Then I read the entire Forem API docs. Not the summary page that everyone reads. The full V1 spec. That's where I found semantic search, concepts, and the analytics endpoints that nobody knew existed.

**Hour 3: Scaffolding**

`pyproject.toml`

, src layout, Click CLI entry point. Boring stuff but I got `devpub --help`

working in 15 minutes. The key decision here: use `httpx`

over `requests`

. httpx gives you connection pooling, proper timeouts, and the async option for later without changing the interface.

**Hour 4-5: The API client**

This is where I spent the most time. Not because the HTTP calls are hard. Because I wanted the client to be production-grade from day one:

The first version didn't have any of this. It just called `raise_for_status()`

and threw ugly `httpx.HTTPStatusError`

exceptions at users. I caught that in testing when I pulled my own 86 articles and hit the rate limit at article 30. The whole thing crashed.

**Hour 6: Testing against my real account**

This is where things got interesting. My first `devpub stats`

call crashed with:

```
TypeError: '>=' not supported between instances of 'dict' and 'int'
```

Turns out the analytics endpoint returns `{"page_views": {"total": 246454}}`

, not `{"page_views": 246454}`

. Nested dicts. No existing tool handles this correctly because no existing tool uses analytics.

The health check endpoint also surprised me. In the V1 API (with the Accept header), `/health_checks/app`

requires authentication. Without the header, it returns 401. So I changed the health check to just call `/users/me`

instead.

**Hour 7: The push --all scare**

During testing, `push --all`

almost published my README.md to Dev.to. The original logic was: find any `.md`

file with a `title`

in frontmatter, push it. My README has YAML frontmatter with a title.

Fixed it by requiring both `title`

AND `published`

keys, and only scanning known directories (`articles/`

, `posts/`

, `content/`

, `drafts/`

). Small thing, but imagine accidentally publishing your CONTRIBUTING.md as a Dev.to article.

**What I'd do differently**

**Start with the pull command, not push.** Pull forces you to understand the API response format before you build the data model. I built the model first based on docs, then had to fix it when real responses looked different.

**Mock tests from the start.** I wrote all the code first, then tests. Should have written the API mock responses alongside the client methods. Would have caught the nested dict issue immediately.

**Ship the rate limiter in v0.0.1.** I initially thought "I'll add that later." Hit the limit within 30 minutes of real testing. Should have been there from commit one.

```
src/devpub/
  api/        # HTTP clients with rate limiting + retries
  cli/        # Click commands + Rich terminal output  
  core/       # Business logic (articles, sync, validation, config)
  templates/  # Article scaffolding (5 templates)
```

Key decisions:

``` bash
$ pytest -v
57 passed in 1.08s
```

Tests mock the HTTP layer with `respx`

. No real API calls in CI. Covers:

```
pip install devpub
export DEVPUB_API_KEY=your_key_here
devpub doctor
```

Or from source:

```
git clone https://github.com/simplynadaf/devpub.git
cd devpub
pip install -e .
```

Get your API key at: [https://dev.to/settings/extensions](https://dev.to/settings/extensions)

Every command returns structured output, handles rate limits silently, and supports `--dry-run`

. AI coding agents (Claude Code, Copilot, Cursor) can use devpub as their publishing layer. The agent writes the article, devpub validates, pushes, and tracks performance. No human needed after the initial setup.

The project is in beta. PRs are welcome. Some things that need help:

`--graph`

flag is accepted but not implemented yetCheck the [issues](https://github.com/simplynadaf/devpub/issues) for `good first issue`

labels.

**GitHub**: [github.com/simplynadaf/devpub](https://github.com/simplynadaf/devpub)

If this saves you time, star the repo. If something's broken, open an issue. If you want a feature, send a PR.

What's your current Dev.to workflow? Are you writing in the browser editor, or do you have a local setup? Curious what pain points people are hitting.

📺 [Watch the full demo on YouTube](https://youtu.be/u8H2BITfYjc)

*Built by* [Sarvar Nadaf](https://sarvarnadaf.com) - Cloud Architect

*Follow me:* [Dev.to](https://dev.to/sarvar_04) | [GitHub](https://github.com/simplynadaf) | [YouTube](https://www.youtube.com/@TechwithSarvar) | [LinkedIn](https://linkedin.com/in/sarvarnadaf)