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**.
devpub push -f articles/my-post.md
devpub pull
devpub stats
devpub dashboard
devpub search "building serverless apps" --semantic
devpub trends
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:
$ 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
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 for good first issue
labels.
GitHub: 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
Built by Sarvar Nadaf - Cloud Architect
Follow me: Dev.to | GitHub | YouTube | LinkedIn