{"_id":"@allenwu06/qreq","name":"@allenwu06/qreq","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@allenwu06/qreq","version":"0.1.0","description":"A deliberately tiny, local-first HTTP request client. `npx qreq req.qreq` sends a request from a plaintext, git-diffable request file — no account, no login, no telemetry, no daemon, no DB. Built for devs who want to do 95% of daily API poking and conscio","type":"module","license":"MIT","private":false,"bin":{"qreq":"bin/qreq.js"},"engines":{"node":">=20"},"scripts":{"test":"vitest run","test:watch":"vitest","qreq":"node bin/qreq.js"},"keywords":["http","api","rest","client","cli","postman","curl","local-first","git-friendly","no-account","tui"],"devDependencies":{"vitest":"^2.1.9"},"_id":"@allenwu06/qreq@0.1.0","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-yIokO0Kw5wvZ1mC/KA5JpH0ZcqGy1I61TfeVvQqwE2jjNpNpirkIEhD6Cmgj24kJ03TI7gsgaBRCHu76ZB4Uyw==","shasum":"d06d567e13817940f7fd0a1649341d1046065f43","tarball":"https://registry.npmjs.org/@allenwu06/qreq/-/qreq-0.1.0.tgz","fileCount":12,"unpackedSize":46098,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIG0KDBIP6URK3QN6jv3XOChxXSb7Fl9yy2zMA4MEpNVwAiBaB6AyuK7s+mUq+3GM5prjz4ei0hzG9mAOdC/viI7HKQ=="}]},"_npmUser":{"name":"allenwu06","email":"allenwu@umich.edu"},"directories":{},"maintainers":[{"name":"allenwu06","email":"allenwu@umich.edu"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/qreq_0.1.0_1779208274425_0.9403391697703722"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-19T16:31:14.296Z","0.1.0":"2026-05-19T16:31:14.592Z","modified":"2026-05-19T16:31:14.896Z"},"maintainers":[{"name":"allenwu06","email":"allenwu@umich.edu"}],"description":"A deliberately tiny, local-first HTTP request client. `npx qreq req.qreq` sends a request from a plaintext, git-diffable request file — no account, no login, no telemetry, no daemon, no DB. Built for devs who want to do 95% of daily API poking and conscio","keywords":["http","api","rest","client","cli","postman","curl","local-first","git-friendly","no-account","tui"],"license":"MIT","readme":"# qreq\n\n**A tiny tool for sending an API request and seeing the response — nothing else.**\n\nYou know the heavy app you open just to fire one HTTP request at an API and\nlook at what comes back? This is the opposite of that. One plain-text file\nformat. No account, no login, no background process, no database, no usage\ntracking. It opens instantly because there is almost nothing to open, and your\nsaved requests live in your code repo as readable text.\n\n```\nnpx @allenwu06/qreq req.qreq\n```\n\n> qreq is built to do **the 95% of everyday API poking you actually do** and\n> to *deliberately refuse* the other 5%. That refused 5% is exactly the weight\n> that made every other tool heavy. **Being tiny is the whole feature.** If\n> you need that 5%, qreq is honestly the wrong tool — and it tells you that up\n> front, not after you've invested in it.\n\n---\n\n## The screenshot\n\n<!-- screenshot placeholder: `qreq users.qreq` showing the colored\n     ✓/✗ per-request lines, statuses, timings, and a PASS/FAIL summary.\n     Intentionally a placeholder — no invented benchmark numbers, no\n     mocked-up UI that the tool does not actually produce. -->\n\n```\n$ qreq users.qreq --env dev.qenv\n✓ login   POST http://api.local/login   200 (12ms)\n✓ me      GET  http://api.local/users/42 200 (4ms)\n\nPASS — 2 request(s)\n```\n\nThat is real output (minus color). There are no fabricated speed claims in\nthis README, on purpose — see *Honesty* below.\n\n---\n\n## Why this exists\n\nThere is a long, repeated, verbatim request from developers for an\n\"unbloated, easy Postman\" — and a running complaint that the usual\nalternatives still feel like a lot (an app, a workspace, an account, a\nsync). qreq is a narrow answer to one specific pain, and it is honest that\nit is narrow. It is not trying to replace those tools' full feature set; it\nis trying to be the thing you reach for when you just want to *send the\nrequest and see the response*, and have that request live in your repo as\nplain text.\n\nIt is good at exactly one thing, or it is no use to you at all:\n\n**tiny · instant-start · no account · plain-text request files that diff in git**\n\nIf that one thing doesn't matter to you, use something else — genuinely.\n\n---\n\n## Install\n\nNothing to install, really:\n\n```\nnpx @allenwu06/qreq path/to/request.qreq\n```\n\nOr add it to a project so a teammate's checkout can run your requests with\nzero setup:\n\n```\nnpm i -D @allenwu06/qreq        # then: npx @allenwu06/qreq api/smoke.qreq --env api/dev.qenv\n```\n\nRequires Node 20+ (uses the built-in `fetch`; **zero runtime\ndependencies** — `npm ls --omit=dev` is empty).\n\n---\n\n## The request file (plain text, diffs in git)\n\nA request file is plain text. A *collection* is one file with several\nnamed requests separated by `### name`. The full grammar is one short page:\n**[SPEC.md](SPEC.md)**. The whole thing:\n\n```\n# users.qreq\n\n### login\n@expect-status 200\n@capture TOKEN = json:token\nPOST {{BASE}}/login\nContent-Type: application/json\n\n{\"user\": \"{{USER}}\", \"pass\": \"{{PASSWORD}}\"}\n\n### me\n@expect-status 200\n@expect-jsonpath user.name == alice\nGET {{BASE}}/me\nAuthorization: Bearer {{TOKEN}}\n```\n\n```\nqreq users.qreq --env dev.qenv          # PASSWORD comes from your shell env\nqreq users.qreq --only me               # run just one named request\nqreq users.qreq --json                  # machine-readable, for CI\n```\n\n- **Variables**: `{{NAME}}` resolves, first hit wins:\n  `@capture`d-this-run → `--env` file → `process.env`.\n- **Secrets**: a real token/password belongs in `process.env`, **never** in\n  the collection. That is the entire point: `git diff` of a collection\n  shows what changed and never leaks a credential. The `.qenv` file is for\n  *non-secret* config (base URLs, ids) and is safe to commit.\n- **Assertions**: `@expect-status` and `@expect-jsonpath` make a collection\n  a CI smoke test (`qreq api/smoke.qreq` → non-zero exit on failure).\n- **Chaining**: `@capture X = json:path` binds a value from one response\n  for use in a later request — no scripting language, by design.\n\n### Exit codes (CI-usable)\n\n| Code | Meaning                                             |\n| ---- | --------------------------------------------------- |\n| `0`  | all requests sent, all assertions passed            |\n| `1`  | usage / file / parse error                          |\n| `2`  | an assertion failed, or a variable was unresolved   |\n| `3`  | a network/transport error reaching the target       |\n\n---\n\n## Coming from Postman / Insomnia / a `curl` you pasted\n\nThere is no importer for proprietary project formats — that is a non-goal\n(below). There **is** a `curl` on-ramp, because a `curl` line is the\nuniversal interchange format everyone already has:\n\n```\nqreq curl import \"curl -X POST https://api/x -H 'A: b' -d '{\\\"k\\\":1}'\" > x.qreq\nqreq curl export x.qreq                       # back to a runnable curl\n```\n\nPaste a `curl` from your browser's devtools or from API docs, get a clean\n`.qreq` file, commit it.\n\n---\n\n## Non-goals (by design — this list is the product)\n\nThese are not \"not yet\". They are **deliberately refused** because each one\nis a documented step on the path to the bloat people are escaping. If you\nneed one of these, qreq is the wrong tool and says so honestly:\n\n- **No account, no login, no cloud sync, no workspace.** A paid *optional*\n  team-sync tier may exist later, wired entirely outside this CLI; the CLI\n  itself will never grow auth or a network call that isn't your request.\n- **No GUI / Electron app.** It is a CLI/terminal tool. That is the whole\n  idea.\n- **No pre-request scripting / JS sandbox / plugin system.** The day a\n  request file can run arbitrary code is the day it stops being a readable\n  plaintext artifact. Use a shell script around qreq if you need logic.\n- **No binary attachments / multipart file-upload builder.** Plaintext\n  bodies only. (You can pipe to `curl` for a one-off upload.)\n- **No full JSONPath / JMESPath / XPath.** Assertions and captures support\n  `a.b.c` and `arr.0.k`. That covers the overwhelming common case; anything\n  more is scope-creep.\n- **No GraphQL/gRPC/WebSocket clients, no mock server, no API designer, no\n  environments-as-a-service, no history UI, no response visualizer.**\n- **No telemetry, ever.** No analytics, no \"anonymous usage stats\", no\n  update-check phone-home.\n\nIf a missing piece is genuinely a *daily* essential (not the 5%), that is\nexactly what we want to hear — see **[FEEDBACK.md](FEEDBACK.md)**. The bar\nfor adding anything is \"a real developer cannot do a normal daily task\nwithout it\", not \"it would be nice\".\n\n---\n\n## The zero-network promise (and how it is enforced)\n\nThe only HTTP request qreq makes is **the one you wrote in the request\nfile**. No update check, no telemetry beacon, no account handshake.\n\nThis is not just a claim — it is a test. `test/no-network.test.js` scans\nevery shipped source file and fails the build if any network call exists\noutside the single sanctioned sender (`src/run.js`), or if any\ntelemetry/account/login primitive appears in the code. The CI also runs the\nwhole suite, and `package-lock.json` has **zero runtime dependencies**\n(only `vitest` for development).\n\nYou can verify it yourself with everything except loopback blocked:\n\n```\ngit clone <repo> && cd qreq && npm ci && npm test\n```\n\nis the entire trust surface. No API key. No external network. No account.\n\n> Note on `npm audit`: it flags advisories in **vitest's dev-only**\n> toolchain (the esbuild/vite dev server). `npm audit --omit=dev` reports\n> **0 vulnerabilities**, because shipped `qreq` has no runtime\n> dependencies — none of that code is ever installed by users.\n\n---\n\n## Honesty\n\n- The output shown above is real (color stripped); there are **no invented\n  benchmark numbers** anywhere in this README. \"Instant start\" means there\n  is no daemon/DB/account to initialize and zero runtime deps to load — not\n  a measured figure we are asking you to take on faith.\n- This is an entrenched space with capable incumbents. qreq is not \"better\n  Postman\". It is a *smaller, different thing* for people who specifically\n  want smaller and different. If that's not you, the incumbents are good —\n  use them.\n- It is young. The format is v1 and intentionally minimal. Tell us what\n  daily task it can't do.\n\n---\n\n## Feedback\n\nWhat did qreq fail to do, or do awkwardly, for a **real** daily task?\nThat's the single most useful thing you can report — it's how we tell a\nmissing-essential from scope-creep we should refuse.\n\nZero-friction: add the **`qreq-feedback`** label to a GitHub issue.\nStructured: the *qreq feedback* issue template. Either way, **your words\nare stored and read exactly as written** — not summarized, not paraphrased.\nSee **[FEEDBACK.md](FEEDBACK.md)**.\n\n## License\n\n[MIT](LICENSE).\n","readmeFilename":"README.md","_rev":"1-51dfc424a67f90e70dbaa997104e2744"}