jev-cli

Ask any text a typed question. Get a probability back, not a paragraph.

jev is a command-line tool for TypeSafe AI's Jev model, the model that never writes text.
Send it some content and a question you defined, get a calibrated probability, and branch on it
in a shell script, a CI job or an AI agent. It is a semantic if statement for your terminal.

Quick start · What can I use it for? · Documentation · Command reference · FAQ

⭐ Useful idea? Star the repo.

It takes two seconds, and it is how the next person finds jev.

🎬 See it in action

Ask a question, get a probability, branch on the exit code, then ask several questions at once.

[!IMPORTANT]
Unofficial project. jev is community-built. It is not affiliated with, endorsed by, or
sponsored by TypeSafe AI. "TypeSafe" and "Jev" belong to their owner. You need a TypeSafe API
key to use it.

🤔 What problem does this solve?

You have text: a support ticket, a commit message, a user's answer, a product review, a model's
output. You need a decision about it: is it angry, which team owns it, how risky is it, should
this pipeline continue?

Today you either write brittle keyword rules, or you ask a large language model and then parse a
sentence it might phrase differently tomorrow.

Jev is a third option. You define the question and the possible answers. The model returns a
number for each one. Your code decides what to do.

jev noul "Is this customer angry?" --state "You charged me twice. Fix it now."

answer  noul  yes  0.91  ██████████████████░░
model jev-1.13.0 (requested jev-latest) · 42 input tokens · est. cost $0.000002 · 1 ms · request req_demo

One question, one number, about a hundredth of a cent. No prompt engineering, no JSON parsing,
no "As an AI language model".

💡 What can I use it for?

Anywhere a program needs a judgment about content. A few that people reach for first:

Each of these is one command:

# Is this message angry? Exit 0 when yes is 0.7 or more, exit 10 when it is not
jev noul "Is this message angry?" --state-file message.txt --fail-under 0.7

# Which team should handle this ticket?
jev choice "Which team should handle this?" --state-file ticket.txt \
  --option billing --option technical --option other

# How frustrated is this customer, on a scale you describe?
jev score "How frustrated is the customer?" --state-file ticket.txt \
  --level Calm --level Frustrated --level "Very angry"

More ideas, and how to phrase a question so it works, in
writing good questions.

⚡ Quick start

Three steps, about a minute, a fraction of a cent.

The install scripts never use sudo, always check the download's SHA-256, and check its
minisign signature when minisign is installed. Homebrew
also sets up the man pages and shell completions. Options, verification and uninstalling are in
the installation guide.

Create one in the TypeSafe console, then either export it,
which is what CI jobs and agents should do:

export TYPESAFE_API_KEY=...

or store it once, in a private file only you can read:

jev auth login
jev auth status

The key is never accepted as a flag value, so it cannot land in your shell history, and only its
last four characters are ever shown.

jev noul "Is this message angry?" --state "You charged me twice. Fix it now."

Piped or redirected, the same command prints JSON instead of a table, and --field noul prints
0.91 and nothing else.

[!TIP]
Ask several questions about the same content in one call. Extra questions cost tokens, not
round trips, and the content is only paid for once.

❓ The three kinds of question

A probability near 0.5 means the model cannot tell, not "medium". --abstain-band 0.4,0.6 turns
that into its own exit code, so those cases can go to a person. Jev reads literally: it cannot
count, do arithmetic or compare dates, so keep that in your code.

Details and worked examples: the three question types.

🧩 Many questions at once

One content, several questions, one call. Write triage.yaml:

model: jev-latest
questions:
  is_urgent:
    type: noul
    instructions: Does this ticket convey urgency?
    criteria:
      "true": Explicitly time-sensitive
      "false": No urgency expressed
  department:
    type: choice
    instructions: Which team should handle this?
    criteria:
      billing: Payments, invoicing, refunds
      technical: Bugs, outages, integrations
      other: ~
  frustration:
    type: score
    instructions: How frustrated is the customer?
    criteria:
      - Calm
      - Frustrated
      - Very angry

Check it for free, then run it:

jev validate -f triage.yaml --state-file ticket.txt
jev eval -f triage.yaml --state-file ticket.txt
jev eval -f triage.yaml --state-file ticket.txt --field answers.department.choice

jev validate sends nothing and needs no key. jev eval --dry-run goes further and prints the
exact request and what it should cost.

To run the same questions over thousands of rows, with concurrency, back-off and a --resume
that survives a crash, use jev batch run: see many rows at once.

🔧 Built for scripts, CI and agents

stdout is data. stderr is everything else. Exit codes are a stable contract, so a script
never has to parse output:

if jev noul "Is this ticket about billing?" --state-file ticket.txt --fail-under 0.7 --quiet; then
  echo "billing"
fi

The full table, gating flags, JSON shapes, the error object and a GitHub Actions example are in
scripting and CI and
exit codes and JSON contract.

🤖 For AI agents

jev treats agents as first-class users, not an afterthought.

• Self-describing. jev spec prints every command, flag, default, exit code and example as
  one JSON document, and every --help says when to use this command rather than its siblings.
• Schemas, not guesswork. jev schema request|questions|batch-record|output|error prints
  JSON Schemas for everything jev reads and writes.
• Free dry runs. jev validate and --dry-run check a request offline, so an agent can fix
  its own mistake before spending anything.
• MCP server. jev mcp serve exposes the same functionality as MCP tools, with a per-call
  spend cap and file access that is deny-by-default.

claude mcp add jev -- jev mcp serve

There is also an agent skill that teaches the whole workflow:

claude plugin marketplace add shaharia-lab/jev-cli
claude plugin install jev@jev-cli

Setup for Claude Desktop, Cursor, VS Code and any other MCP client, plus the spend caps, is in
AI agents and MCP.

🔐 Privacy and security

• No telemetry, ever. jev contacts exactly two hosts: the TypeSafe API when you evaluate
  something, and GitHub Releases when it checks for an update, which you can turn off.
• Your content stays yours. It goes to the API and nowhere else, and is never written to a
  log unless you explicitly ask for that.
• The key is never exposed. Not as a flag, not in logs, errors, dry-run output or MCP
  results. Only its last four characters are ever shown.
• HTTPS only, certificate verification cannot be disabled, and redirects are never followed.
• Signed updates. Every download is checked against a signature and a checksum before
  anything is replaced, and jev never downgrades on its own.

SECURITY.md has the full model, how to verify a release yourself, and how to
report a vulnerability privately. Please do not open a public issue for one.

📚 Documentation

jev --help          # every command
jev spec            # the whole contract, as JSON
jev schema request  # what a request file may contain

🙋 FAQ

An LLM writes a sentence you then have to parse, and it may phrase things differently tomorrow.
Jev returns a number in a shape you specified, so your code can branch on it. It is also much
faster and much cheaper, because it generates nothing. It is not a replacement for an LLM: it is
the piece you reach for when the job is a decision.

Only input tokens are billed, so a short ticket costs a small fraction of a cent. jev always
labels a cost as an estimate, and --dry-run prices a run before you send it.

Yes, for anything that evaluates content. Everything offline is free and needs no key:
jev validate, jev schema, jev spec, jev completion and any command with --dry-run.

Not bit for bit. Compare against thresholds, never for equality, and pin a versioned model such
as jev-1.13.0 for anything that must stay stable. The alias jev-latest moves to new versions
without notice.

Yes. jev batch run streams JSONL or CSV, so memory does not grow with the file, backs off when
the API rate limits, writes one JSON record per row, and picks up where it stopped with
--resume.

In TYPESAFE_API_KEY, or in a private credentials file with mode 0600. There is no OS keychain
and no browser flow, by design.

More answers: the full FAQ and
troubleshooting.

⭐ Spread the word

jev is a young project around a young model. The fastest way to keep it alive is to make it
easier for the next person to find.

🤝 Contributing

Pull requests are welcome. CONTRIBUTING.md explains the workflow and the
quality gates, and CLAUDE.md is the architecture guide that contributors and AI
agents both work from.

git clone https://github.com/shaharia-lab/jev-cli
cd jev-cli
make check          # everything CI runs

Security problems go privately through SECURITY.md, never a public issue.

Licence

Licensed under either of Apache License, Version 2.0 or
MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in
this project by you, as defined in the Apache-2.0 licence, shall be dual licensed as above,
without any additional terms or conditions.