@tempr/cli 0.9.9

package/README.md

@@ -0,0 +1,275 @@
+# Tempr CLI
+
+Sign in, chat, and run agentic coding tasks against your Tempr license from the terminal.
+
+## Install
+
+The standalone builds need nothing installed first -- no .NET, no Node.
+
+**macOS and Linux**
+
+```
+curl -fsSL https://temprhq.io/cli/install.sh | sh
+```
+
+**Windows**
+
+```
+irm https://temprhq.io/cli/install.ps1 | iex
+```
+
+Or download an archive for your platform from https://temprhq.io/cli#downloads (the current release
+is always at `https://temprhq.io/cli/latest/tempr-<rid>.zip` or `.tar.gz`, for `win-x64`,
+`win-arm64`, `osx-arm64`, `osx-x64`, `linux-x64` and `linux-arm64`) and put `tempr` on your `PATH`;
+each one ships with a `.sha256` next to it. `tempr update` checks for a newer release and tells you
+the command that installs it.
+
+`install.sh` installs to `~/.local/bin` (override with `TEMPR_INSTALL_DIR`); `install.ps1` installs
+to `%LOCALAPPDATA%\Programs\tempr` (override with `-InstallDir`) and adds it to your user `PATH`.
+
+Binaries aren't code-signed yet, so the first run may meet a SmartScreen or Gatekeeper warning.
+The install scripts avoid it on macOS and Linux.
+
+## Quick start
+
+```
+tempr auth                     # sign in through your browser, or with your license key
+tempr keys add                 # add a key for a model provider (OpenAI, Anthropic, ...)
+tempr config set-model <id>    # set a default model
+tempr doctor                   # check everything is set up (exits non-zero if not)
+tempr "explain this repo"      # one-shot
+tempr                          # interactive session
+```
+
+## Usage
+
+- `tempr "<prompt>"` -- one-shot agent turn with real tool-calling (file read/write/edit, run_command, semantic search).
+- `tempr` -- interactive REPL with persistent history and tab-completion for `/commands` and `@personas`. The first run plays a short animated ASCII logo; `TEMPR_LOGO=1` plays it again, `TEMPR_NO_LOGO` skips it, and `NO_COLOR` shows a plain one-line name instead of the animation.
+- `<something> | tempr` -- headless/piped mode: with no prompt argument, stdin is the whole prompt (`{ echo "review this:"; git diff; } | tempr`). Given a prompt argument, stdin is ignored.
+- `tempr --ask "<prompt>"` -- plain chat, no tools.
+- `tempr "@debugger why does this fail"` -- run a specialist persona. In the REPL, `/persona` opens a picker to switch personas for the rest of the session instead of typing `@name` every turn.
+- `@workspace`/`#codebase` anywhere in a message attaches a brief workspace overview; `@problems`/`@diagnostics` attaches current compiler errors/warnings (via `dotnet build`/`tsc --noEmit`); `@relative/path/to/file` attaches that file -- images (`.png`/`.jpg`/`.gif`/`.webp`/`.bmp`) go in as real image content, other files as inline text.
+- Workspace instructions: every agent turn carries `AGENTS.md` and `.github/copilot-instructions.md` from the current directory, other agents' files (`CLAUDE.md`, `GEMINI.md`, `.cursorrules` and Cursor rules in `.cursor/rules` that always apply; the others are listed with their description for the agent to read when relevant), then a global `~/.tempr/AGENTS.md` for every workspace, each under its own heading and 16 KB combined at most. Where they disagree, AGENTS.md wins. `--verbose` names the files it found.
+- `tempr auth` signs in through your browser: it shows a code, opens the Tempr portal, and you approve the sign-in there -- on any device, so it works over SSH too. `tempr auth --browser` skips the question; `tempr auth <key>` or `TEMPR_LICENSE_KEY` still sign in with a license key, for scripts and CI. Running `tempr` for the first time walks through signing in, adding a provider key and picking a model.
+- `tempr -c` resumes this folder's most recent session; `/resume` picks one from a list.
+- `!command` in the REPL runs a command yourself -- `!git status` -- in this folder, and its output goes in front of your next message. No approval: it's your own command.
+- A turn that runs 30 seconds or more rings the terminal bell when it's done or needs approval, with a desktop notification where the terminal shows one; `tempr config set-notifications off` or `TEMPR_NO_NOTIFY` turns it off.
+- `/diff` shows what the last turn changed on disk, and `/undo` puts it back -- skipping any file that has changed since, so an undo never overwrites work it didn't make.
+- `tempr keys` lists your provider keys -- Tempr calls every model with your own key for its provider. `tempr keys add [provider]` adds or replaces one (no provider opens a picker), and `tempr keys remove <provider>` removes one; `/keys` does the same inside the REPL. The key is typed at a hidden prompt, piped in on stdin, or read with `--from-env VARIABLE` -- never passed as an argument, where it would land in shell history. Tempr checks it with the provider before saving it; a key the provider rejects isn't saved unless you say so or pass `--force`, and one that couldn't be checked (the provider was down, or offers no way to check) is saved with a note. Azure OpenAI, Azure AI Foundry, AWS Bedrock and custom endpoints need more than a key, so they're set up on the Portal's Provider keys page; on a Team plan, your organization's admin manages keys.
+- `tempr models` lists the models your licence can use, with prices and context sizes; `/model` with no argument opens a picker over the same list.
+- `tempr init` drafts an `AGENTS.md` for this workspace from a scan of what's in it.
+- `tempr usage` shows what this machine's turns have cost, by model.
+- `tempr completion bash|zsh|fish|powershell` prints a completion script.
+- `tempr config`, `tempr history`, `tempr mcp`, `tempr doctor` -- manage config, saved sessions, MCP servers, and connectivity. `tempr mcp browse` (or `/mcp browse` in the REPL) opens a picker over Tempr's curated MCP catalog.
+- Agent-mode tools also include `get_diagnostics`, `search_symbols` (where a name is defined, then where it's used, in C#, TypeScript and JavaScript, Python, Go, Rust, Java, Kotlin, C and C++, Swift, Ruby and PHP), `get_callers`/`get_callees` (lexical, not a real language server), and `get_solution`/`get_projects`/`get_project_references`/`get_tests`/`run_tests`/`get_test_results` for .NET workspaces.
+- Web search: on an Anthropic, OpenAI or xAI model, the agent can search the web with the provider's own search, shown as `Searching the web for "…"`. The provider runs the search and bills it to your key for that provider, on top of the tokens: $10 per 1,000 searches on Anthropic and OpenAI, and $5 per 1,000 on xAI, where opening a page counts as a search too; the cost `tempr usage` and the Portal show includes it. It's on in an interactive session and off in scripts (`--json`, piped input, `CI`); `--search` and `--no-search` decide for one run, and `tempr config set-web-search off` turns it off for interactive sessions too. The pages a search finds are ones the agent may then open with `web_fetch`.
+- Chat history (`~/.tempr/sessions/`) and auth tokens are both encrypted at rest (DPAPI on Windows, AES-256-GCM elsewhere).
+
+## Approval modes
+
+Mutating tool calls -- file writes, patches, commands and MCP calls -- are gated by an approval
+mode. `tempr config set-approval-mode <mode>` sets the default; `--yolo` uses `autopilot` for one
+run without changing it, and on Linux puts its commands in the sandbox (see below).
+
+| Mode | File edits and MCP calls | Commands |
+|---|---|---|
+| `interactive` (default) | asks | asks |
+| `autopilot` | run | allow-listed commands run; ones that delete, publish, force-push, reset or reboot, and anything not allow-listed, ask |
+| `bypass` | run | always asks -- **stricter than `autopilot`**, despite the name |
+
+The mode names are shared with Tempr's IDE extensions, which is why `bypass` reads the way it does.
+`autopilot` is the one to use unattended. With no terminal to ask on (piped input, `--json`, CI), a
+call that would have asked is refused and the model is told why.
+
+The allow-list starts with read-only commands and each ecosystem's build, test, lint and type-check
+commands: `dotnet build`/`test`, `npm test` and `npm run build`/`test`/`lint`/`typecheck` (and
+the pnpm, yarn and bun equivalents), `pytest`, `go build`/`test`/`vet`, `cargo
+build`/`check`/`test`/`clippy`, `mvn compile`/`test`, `gradle build`/`test` and their wrapper
+scripts, `git status`, `git log` and the like. Other `package.json` scripts (`npm run deploy`)
+aren't on it. A prefix covers whole words: `npm run build` doesn't cover `npm run build-and-deploy`.
+Add to it per machine with `tempr config allow-command <prefix>`, or per repository with an
+`.agentcommands.json` file at the workspace root: `{ "allowedPrefixes": ["docker build"] }`.
+
+Each turn tells the model which projects the workspace holds -- a few folders deep, so a monorepo's
+projects are listed with their folders -- and how each one builds and tests. A command runs in the
+workspace root or, with `working_directory`, a folder inside it (chaining `cd` is refused). It's
+stopped after 2 minutes unless the model asks for longer, up to 10, and long output keeps its start
+and its end. The .NET-only tools (projects, references, tests) are offered only where there's a .NET
+project.
+
+Every tool path is checked against the current directory, including through symbolic links and
+Windows junctions, so a link inside the workspace can't be used to read or write outside it.
+
+## Sandbox (Linux)
+
+`--sandbox` runs the agent's commands inside a sandbox. They can change files only in the current
+folder, the temp folders and the package stores and caches builds write to (npm's, pip's, NuGet's,
+Go's, Cargo's, Gradle's and Maven's), and they can't open network connections. Reading is open.
+`tempr config set-sandbox on` turns it on for every run; `--no-sandbox` turns it off for one.
+
+**On by default for `--yolo` and CI.** A run on autopilot with nobody deciding command by command
+(`--yolo`, `--approval-mode autopilot`, or autopilot in CI) runs its commands in the sandbox with the
+network on: the file limits hold, and installs, restores and tests that use localhost still work.
+Where the sandbox can't run, those runs go ahead unsandboxed, as before, and an interactive session
+says so. `--sandbox` asks for the network off as well; `--no-sandbox`, or
+`tempr config set-sandbox off`, keeps `--yolo` out of the sandbox. Other runs aren't sandboxed
+unless asked: the sandbox would let their commands run without asking.
+
+Inside the sandbox any command runs without asking, in every approval mode, so an unattended run can
+build, test and try things it has no allow-list entry for. Commands that delete, publish or
+force-push still ask. When a command fails because the sandbox blocked it -- a download, say -- the
+agent can ask to run it outside the sandbox, which always asks you first; a run with nobody to ask
+refuses it.
+
+dotnet in the sandbox keeps its own per-user files in `~/.cache/tempr/sandbox-dotnet` rather than
+`~/.dotnet`, which holds global tools and stays read-only; it restores into your own
+`~/.nuget/packages` and reads your NuGet package sources.
+
+- **What it covers:** `run_command`, the .NET test tools and `get_diagnostics`. Not `!command`,
+  which you type yourself, and not MCP servers.
+- **Git hooks:** a command may not keep changes to `.git/hooks`, `.git/config` or
+  `.agentcommands.json`, which run or allow things later, outside the sandbox. Tempr puts back
+  anything a command changed there and tells the agent.
+- **The network:** `--sandbox-network` (or `set-sandbox network`) keeps the file limits and leaves
+  the network on. Cutting the network off blocks TCP only, so name lookups still work.
+- **Where it runs:** Linux 5.13 or later, and 6.7 or later to cut off the network, through the
+  kernel's Landlock. It needs no install and no privileges, and works in a container and on
+  Ubuntu 24.04. On macOS and Windows it isn't available yet (inside WSL2 it works). If you ask for
+  the sandbox where it can't run, nothing runs: the CLI exits with code 7 rather than run your
+  commands unsandboxed. `tempr doctor` says what this machine supports.
+
+## Your own commands and agents
+
+Markdown files, shared with Tempr Code. Put them in `.tempr/` in a project to commit them with it,
+or in `~/.tempr/` to have them everywhere.
+
+`.tempr/commands/deploy.md` — invoked as `/deploy staging`:
+
+```markdown
+---
+description: Walk through a deploy
+persona: devops
+---
+
+Deploy to $ARGUMENTS. Check the health endpoint afterwards and report what you saw.
+```
+
+`$ARGUMENTS` is everything after the command name; `$1`…`$9` are its whitespace-separated words.
+
+`.tempr/agents/dba.md` — invoked as `@dba what's slow about this query`:
+
+```markdown
+---
+description: Database specialist
+allowed-tools: read_file, search_files, run_command
+model: anthropic/claude-opus-4-5
+---
+
+You know this schema inside out. Prefer an index over a rewrite, and always explain the plan.
+```
+
+`/commands` and `/agents` list what's available, and both complete on Tab.
+
+## Headless and CI
+
+`--json` writes one event per line and then a final result object:
+
+```bash
+tempr --json --yolo "fix the failing test" | tail -1 | jq '{status, summary, files: .filesChanged}'
+```
+
+| Exit code | Meaning |
+|---|---|
+| 0 | the turn finished |
+| 1 | something went wrong (server, network, tool, unhandled error) |
+| 2 | the command line didn't make sense |
+| 3 | not signed in, session expired, or no active plan |
+| 4 | hit the step limit with work still to do |
+| 5 | a tool call was refused and the turn carried on without it |
+| 6 | stopped at `--max-cost` |
+| 7 | the sandbox was asked for and can't run here, so nothing ran |
+| 130 | interrupted (Ctrl+C) |
+
+Useful flags for an unattended run: `--max-turns`, `--max-cost` (stop once the run's model calls
+have cost this many dollars), `--allowed-tools`, `--disallowed-tools`, `--approval-mode`,
+`--prompt-file`, and `--search` to let the model search the web, which a script doesn't do unless
+asked. The first `--json` line is a `session` object (session id, model, settings), and each tool the
+CLI runs locally adds a `tool-result` line with its output. Sign in with `TEMPR_LICENSE_KEY` rather than on a command line,
+where the key would land in shell history and in every process listing on the machine. Setting `CI`
+turns off the logo, the update check and crash reports, and makes any call that would have asked a
+question refuse instead of waiting.
+
+There's a GitHub Action at the repository root; `docs/examples/tempr-agent-workflows.md` has a
+PR-review workflow and a fix-the-build workflow built on it.
+
+## In your editor (Agent Client Protocol)
+
+`tempr acp` runs Tempr as an [Agent Client Protocol](https://agentclientprotocol.com) agent, which
+an editor starts and talks to over stdin and stdout: Zed, JetBrains AI Assistant, Neovim
+(CodeCompanion, avante.nvim) and Emacs (agent-shell) among them. In Zed's `settings.json`:
+
+```json
+{
+  "agent_servers": {
+    "Tempr": { "type": "custom", "command": "tempr", "args": ["acp"] }
+  }
+}
+```
+
+In JetBrains IDEs, the same entry goes under `agent_servers` in `~/.jetbrains/acp.json`, with the
+full path to `tempr` as the command; AI Chat's ⋮ menu > Add Custom Agent opens that file.
+
+The editor shows Tempr's replies, its tool calls (edits as diffs) and its questions, and you answer
+them there. Tempr runs its tools itself, so the allow-list, the approval mode and, on Linux, the
+[sandbox](#sandbox-linux) work as they do here; autopilot in an editor counts like `--yolo`. Sign in
+with `tempr auth` first, or from the editor, which offers the browser sign-in.
+
+- **Sessions** are saved like any other, so `tempr history` lists them and `tempr -c` in the same
+  folder carries one on. The editor's own session list shows them too, and opening one there
+  replays its conversation (the text; tool calls aren't kept).
+- **Settings:** the approval mode, the model, its reasoning level and web search, for that session.
+  A new session starts on the model last picked in an editor, or on your default until you pick one
+  (`tempr config set-model` makes the default the starting model again). A reasoning level is kept
+  per model, as `/reasoning` keeps it.
+- **Slash commands:** your command templates, plus `/undo`, `/diff` and `/agents`.
+- **MCP servers** the editor passes run beside yours from `~/.tempr/mcp.json`; one with the same name
+  as one of yours takes its place for the session.
+- **Command output** streams into a terminal under the call, in editors that draw one (Zed); in
+  others it shows when the command ends.
+- **Sub-agents** answer under the call that delegated to them, apart from the reply.
+
+It passes the ACP conformance kit ([acp-tck](https://github.com/agentclientprotocol/acp-tck)). The
+setup for each editor is at <https://temprhq.io/docs/cli-editors>.
+
+## What leaves your machine
+
+Everything below goes to your Tempr server (`api.temprhq.io` unless the `TEMPRAPP_SERVER_URL`
+environment variable or a `serverUrl` entry in `~/.tempr/config.json` says otherwise), which relays model calls to the providers your license has keys for.
+
+**Sent on every turn you send**
+
+- Your message, and the conversation so far in this session.
+- `AGENTS.md`, `.github/copilot-instructions.md`, `CLAUDE.md`, `GEMINI.md` and Cursor rules from the
+  current directory, and `~/.tempr/AGENTS.md`, up to 16 KB combined.
+- Files you attach with `@path`, including images, and anything `@workspace` or `@problems` pulls
+  in (a workspace overview, or your current build errors).
+- The contents of files the agent reads or searches, as tool results.
+- Your operating system, CPU architecture and which shell `run_command` would use, so the model
+  writes commands that work on your machine, and the projects found in the current directory, with
+  their folders and build and test commands.
+
+**Sent only if you say yes**
+
+- Crash reports: the error type and message, the stack trace, the CLI version and your OS version.
+  Off by default. The first interactive session asks once and remembers your answer; change it with
+  `tempr config set-crash-reports on|off`. Nothing is ever sent when there's no terminal to ask on
+  (piped input, `--json`), or when `CI`, `DO_NOT_TRACK` or `TEMPR_NO_CRASH_REPORTS` is set.
+
+**Never sent**
+
+- Your license key after sign-in (it is exchanged once for a session token).
+- Any file the agent didn't read, and any command output you didn't approve.
+- Telemetry: there is none beyond the requests above.
+
+See `tempr --help` for the full command reference, and `docs/plans/plan-tempr-cli-v1-roadmap.md` in
+the Tempr repo for design notes.

package/bin/tempr.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Hands off to the platform package npm installed for this machine. A shim rather than a
+// postinstall download: nothing is fetched at install time, so the package works behind a proxy,
+// in an offline cache, and in a lockfile that means what it says.
+const { spawnSync } = require('node:child_process');
+
+const pkg = `@tempr/cli-${process.platform}-${process.arch}`;
+let binary;
+try {
+    binary = require.resolve(`${pkg}/bin/tempr${process.platform === 'win32' ? '.exe' : ''}`);
+} catch {
+    console.error(`The Tempr CLI has no build for ${process.platform} ${process.arch}.`);
+    console.error(`Expected ${pkg} to be installed. If your installer skips optional dependencies, install it directly.`);
+    process.exit(1);
+}
+
+const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' });
+if (result.error) {
+    console.error(result.error.message);
+    process.exit(1);
+}
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -0,0 +1,17 @@
+{
+    "name": "@tempr/cli",
+    "version": "0.9.9",
+    "description": "Sign in, chat, and run agentic coding tasks against your Tempr license from the terminal.",
+    "homepage": "https://temprhq.io",
+    "license": "SEE LICENSE IN README.md",
+    "bin": { "tempr": "bin/tempr.js" },
+    "files": ["bin/"],
+    "optionalDependencies": {
+        "@tempr/cli-win32-x64": "0.9.9",
+        "@tempr/cli-win32-arm64": "0.9.9",
+        "@tempr/cli-linux-x64": "0.9.9",
+        "@tempr/cli-linux-arm64": "0.9.9",
+        "@tempr/cli-darwin-x64": "0.9.9",
+        "@tempr/cli-darwin-arm64": "0.9.9"
+    }
+}