Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): add CLI model settings (#1944)

Casey Gowrie672c05444b04
diff --git a/.changeset/bright-ravens-model.md b/.changeset/bright-ravens-model.md
new file mode 100644
index 000000000..f4579c025
--- /dev/null
+++ b/.changeset/bright-ravens-model.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Add `eve set` with `--model` and `--reasoning` options for changing an existing agent's model settings, and add the same model settings to `eve init` for scaffolding.
diff --git a/docs/agent-config.md b/docs/agent-config.md
index 20e84d7e5..2fbde3dc2 100644
--- a/docs/agent-config.md
+++ b/docs/agent-config.md
@@ -17,6 +17,10 @@ export default defineAgent({
});
```
+For a static AI Gateway model ID, you can make the same source change from the
+project root with `eve set --model anthropic/claude-opus-4.8` or from the local
+dev TUI with `/model anthropic/claude-opus-4.8`.
+
The root `agent.ts` can be omitted when no runtime config is needed. In that case, eve defaults
to `anthropic/claude-sonnet-5`. When `agent.ts` is present, `model` is required.
@@ -103,6 +107,7 @@ Supported values are `"provider-default"`, `"none"`, `"minimal"`, `"low"`,
`"medium"`, `"high"`, and `"xhigh"`. The selected model and provider determine
which levels are available and how they map to provider-native settings. Use
`modelOptions.providerOptions` when you need provider-specific reasoning controls.
+Run `eve set --reasoning high` to update this field from the command line.
## Compaction
diff --git a/docs/installation.mdx b/docs/installation.mdx
index c1d3ce0e3..847ad0f94 100644
--- a/docs/installation.mdx
+++ b/docs/installation.mdx
@@ -24,6 +24,12 @@ npx eve@latest init my-agent
The command creates `my-agent/`, installs dependencies, and initializes Git. If a supported coding-agent REPL is available, eve offers to start the development server, open the REPL, or exit after scaffolding.
+Pass an AI Gateway model ID or reasoning effort when you do not want the defaults:
+
+```bash
+npx eve@latest init my-agent --model openai/gpt-5.5 --reasoning high
+```
+
## Run the agent
From the project root, run the generated development command:
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index ec7a9b14d..857e45f1c 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -1,6 +1,6 @@
---
title: "CLI"
-description: "Reference for every eve CLI command: init, info, build, start, dev, logs, trace, link, deploy, eval, channels, and extension."
+description: "Reference for every eve CLI command: init, set, info, build, start, dev, logs, trace, link, deploy, eval, channels, and extension."
---
The `eve` binary (`bin: eve`) runs from your app root, and every command first loads `.env`/`.env.local` from that root. Running `eve` with no command runs `eve dev`.
@@ -26,6 +26,7 @@ The `eve` binary (`bin: eve`) runs from your app root, and every command first l
| `eve channels list` | List user-authored channels |
| `eve extension init [target]` | Create a new extension package |
| `eve extension build` | Build the current package as an extension |
+| `eve set` | Change the root agent's model and reasoning effort |
| `eve add <item>` | Install an item from the official or a configured shadcn registry |
| `eve registry <command>` | Add sources and list, search, or view registry catalog items |
@@ -34,7 +35,7 @@ When `eve build` fails on discovery errors, it prints the full diagnostics repor
## `eve init`
```bash
-eve init [target] [--channel-web-nextjs]
+eve init [target] [--model <provider/model-id>] [--reasoning <effort>] [--channel-web-nextjs]
```
Creates a new agent app or adds an agent to an existing app. Always installs dependencies. New directories also initialize Git.
@@ -47,9 +48,11 @@ Creates a new agent app or adds an agent to an existing app. Always installs dep
After scaffolding, a human terminal usually continues into `eve dev`. If a coding-agent REPL is on `PATH`, the handoff menu can open it instead or exit without starting either process. Coding-agent launches print the next steps instead of opening the TUI, so the session does not get stuck. Fresh projects use the parent workspace's package manager when there is one; otherwise they use the manager that launched `eve init`.
-| Flag | Type | Default | Description |
-| ---------------------- | ---- | ------- | ---------------------------------------------------------------------------------------------------- |
-| `--channel-web-nextjs` | flag | off | Add the Web Chat app (Next.js). Not for existing projects — run `eve add channel/web` there instead. |
+| Flag | Type | Default | Description |
+| ---------------------- | ------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `--model <model>` | string | `anthropic/claude-sonnet-5` | Set the root agent's AI Gateway model ID. |
+| `--reasoning <effort>` | enum | provider default | Set reasoning to `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. `provider-default` leaves the field unauthored. |
+| `--channel-web-nextjs` | flag | off | Add the Web Chat app (Next.js). Not for existing projects — run `eve add channel/web` there instead. |
## `eve extension`
@@ -81,6 +84,28 @@ eve extension build
Builds the complete agent-shaped extension tree into its configured dist root, emits declarations and compatibility metadata, and fills the package `exports` map. The original TypeScript source is not required in the published package.
+## Set model settings
+
+Change the root agent's AI Gateway model and reasoning effort without opening the dev TUI:
+
+```bash
+eve set \
+ --model openai/gpt-5.6-sol \
+ --reasoning high
+```
+
+Pass either flag by itself to change one setting. When you pass both, eve writes
+them to `agent/agent.ts` in one source edit. `--reasoning` accepts
+`provider-default`, `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`;
+`provider-default` removes the authored `reasoning` field.
+
+The command uses the same model ID validation and source editor as `/model` in
+the local dev TUI. It does not configure model credentials. The `--model` flag
+cannot rewrite models defined with `defineDynamic`, an environment expression,
+or a provider-authored SDK model; change those models in `agent.ts`.
+`--reasoning` can still update an editable root config when its model comes from
+an SDK call.
+
## Registry items
Commands for installing and discovering [shadcn registry](https://ui.shadcn.com/docs/registry) items. Official registry items use a kind and slug (for example, `extension/agent-browser`); URLs and configured registry addresses are also supported.
diff --git a/packages/eve/README.md b/packages/eve/README.md
index 6a2ed25cb..23f51637e 100644
--- a/packages/eve/README.md
+++ b/packages/eve/README.md
@@ -122,12 +122,14 @@ export default defineAgent({
npx eve@latest init my-agent
```
-`eve init` writes a new agent with eve's default model. Pass `--channel-web-nextjs` to add the
-Web Chat application. It installs dependencies, initializes Git, and starts the
-development server. When it finds a supported coding-agent REPL, the handoff
-menu can open that REPL instead or exit. Targeting an existing project directory
-(`eve init .`) adds the agent files and missing dependencies instead. It does
-not create a Vercel project or deploy the agent.
+`eve init` writes a new agent with eve's default model. Pass `--model
+openai/gpt-5.5` to choose another AI Gateway model, `--reasoning high` to set a
+reasoning effort, or `--channel-web-nextjs` to add the Web Chat application. It
+installs dependencies, initializes Git, and starts the development server. When
+it finds a supported coding-agent REPL, the handoff menu can open that REPL
+instead or exit. Targeting an existing project directory (`eve init .`) adds the
+agent files and missing dependencies instead. It does not create a Vercel
+project or deploy the agent.
CLI commands:
@@ -136,6 +138,7 @@ CLI commands:
- `eve build` — compile `.eve/` and build the host output
- `eve start` — serve the built `.output/` app
- `eve dev` — start the local runtime and REPL
+- `eve set [--model <model-id>] [--reasoning <effort>]` — change root model settings
- `eve extension init <name>` — create a new extension package
- `eve extension build` — build an extension package
diff --git a/packages/eve/src/cli/commands/agent-instructions.test.ts b/packages/eve/src/cli/commands/agent-instructions.test.ts
index e85ff6423..28ccb66e0 100644
--- a/packages/eve/src/cli/commands/agent-instructions.test.ts
+++ b/packages/eve/src/cli/commands/agent-instructions.test.ts
@@ -23,6 +23,8 @@ describe("initAgentInstructions", () => {
expect(instructions).toContain("ask the user to confirm it");
expect(instructions).toContain("Web Chat");
expect(instructions).toContain("--channel-web-nextjs");
+ expect(instructions).toContain("--model provider/model-id");
+ expect(instructions).toContain("--reasoning effort");
// `npx` runs without a prior install and is package-manager agnostic, so the
// pre-scaffold guide renders the universal `npx eve dev` through the shared
// prompt renderer rather than a launcher-specific command.
diff --git a/packages/eve/src/cli/commands/agent-prompt/collect-intent.md b/packages/eve/src/cli/commands/agent-prompt/collect-intent.md
index 8731320ed..faf43160d 100644
--- a/packages/eve/src/cli/commands/agent-prompt/collect-intent.md
+++ b/packages/eve/src/cli/commands/agent-prompt/collect-intent.md
@@ -16,3 +16,6 @@ the coding harness's prompt tools when available, and do not guess.
under `agent/connections/`. When a system needs every end-user to sign in, wire
its auth through **Vercel Connect** (`connect()` from `@vercel/connect/eve`),
which handles consent, encrypted token storage, and refresh.
+4. Does the user want a specific AI Gateway model or reasoning effort? If so,
+ pass its `provider/model-id` to `eve init --model` and its reasoning effort to
+ `--reasoning`; otherwise, use eve's defaults.
diff --git a/packages/eve/src/cli/commands/agent-prompt/scaffold.md b/packages/eve/src/cli/commands/agent-prompt/scaffold.md
index 19af3ee49..fd80700b1 100644
--- a/packages/eve/src/cli/commands/agent-prompt/scaffold.md
+++ b/packages/eve/src/cli/commands/agent-prompt/scaffold.md
@@ -4,7 +4,7 @@ First settle the target: a new project, or the agent added to an existing
directory? For a new project, propose a name and ask the user to confirm it; for
an existing one, ask for the directory.
-For a new project, run (append `--channel-web-nextjs` only if the user wants Web
+For a new project, run (`--channel-web-nextjs` is only for users who want Web
Chat):
npx eve@latest init <name>
@@ -18,5 +18,7 @@ If the user wants a reusable extension package instead of an agent, run
For an existing app, run `npx eve@latest init .` from its directory. This adds the
agent and missing dependencies while leaving the existing Git repository and app
-scripts alone. If init cannot be used, install by hand with
+scripts alone. Append `--model provider/model-id` or `--reasoning effort` to
+either init command when the user chose those settings. If init cannot be used,
+install by hand with
`npm install eve@latest ai zod`; manual installation does not add package scripts.
diff --git a/packages/eve/src/cli/commands/init.integration.test.ts b/packages/eve/src/cli/commands/init.integration.test.ts
index da4a02f34..4af944d0f 100644
--- a/packages/eve/src/cli/commands/init.integration.test.ts
+++ b/packages/eve/src/cli/commands/init.integration.test.ts
@@ -76,6 +76,7 @@ function dependencies(
spawnCodingAgentRepl: ReturnType<typeof vi.fn<InitCommandDependencies["spawnCodingAgentRepl"]>>;
spawnPackageManager: ReturnType<typeof vi.fn<InitCommandDependencies["spawnPackageManager"]>>;
tryInitializeGit: ReturnType<typeof vi.fn<InitCommandDependencies["tryInitializeGit"]>>;
+ validateModelSlug: ReturnType<typeof vi.fn<InitCommandDependencies["validateModelSlug"]>>;
} {
return {
addAgentToProject: (options: AddAgentToProjectOptions) => {
@@ -110,6 +111,7 @@ function dependencies(
spawnCodingAgentRepl: vi.fn(async () => true),
spawnPackageManager: vi.fn(async () => true),
tryInitializeGit: vi.fn(async () => gitResult),
+ validateModelSlug: vi.fn(async () => null),
};
}
@@ -189,6 +191,60 @@ describe("runInitCommand", () => {
expect(output.messages[3]).toContain("$ eve dev");
});
+ it("creates a new agent with model settings selected by init options", async () => {
+ const parentDirectory = await mkdtemp(join(tmpdir(), "eve-init-model-"));
+ const output = logger();
+ const deps = dependencies();
+
+ await runInitCommand(
+ output,
+ parentDirectory,
+ "my-agent",
+ { model: "openai/gpt-5.5", reasoning: "high" },
+ deps,
+ );
+
+ const projectPath = join(parentDirectory, "my-agent");
+ const agentSource = await readFile(join(projectPath, "agent/agent.ts"), "utf8");
+ expect(agentSource).toContain('model: "openai/gpt-5.5"');
+ expect(agentSource).toContain('reasoning: "high"');
+ expect(deps.validateModelSlug).toHaveBeenCalledWith(
+ expect.stringContaining(".eve-init-"),
+ "openai/gpt-5.5",
+ );
+ });
+
+ it("omits authored reasoning when init uses the provider default", async () => {
+ const parentDirectory = await mkdtemp(join(tmpdir(), "eve-init-reasoning-default-"));
+ const output = logger();
+ const deps = dependencies();
+
+ await runInitCommand(
+ output,
+ parentDirectory,
+ "my-agent",
+ { reasoning: "provider-default" },
+ deps,
+ );
+
+ const agentSource = await readFile(join(parentDirectory, "my-agent", "agent/agent.ts"), "utf8");
+ expect(agentSource).not.toContain("reasoning:");
+ });
+
+ it("rejects an invalid --model before creating the project", async () => {
+ const parentDirectory = await mkdtemp(join(tmpdir(), "eve-init-model-invalid-"));
+ const output = logger();
+ const deps = dependencies();
+ deps.validateModelSlug.mockResolvedValue("Unknown model.");
+
+ await expect(
+ runInitCommand(output, parentDirectory, "my-agent", { model: "unknown/model" }, deps),
+ ).rejects.toThrow("Unknown model.");
+
+ await expect(pathExists(join(parentDirectory, "my-agent"))).resolves.toBe(false);
+ expect(deps.runPackageManagerInstall).not.toHaveBeenCalled();
+ });
+
it("opens the selected coding-agent REPL instead of starting eve dev", async () => {
const parentDirectory = await mkdtemp(join(tmpdir(), "eve-init-repl-handoff-"));
const output = logger();
@@ -781,6 +837,26 @@ describe("runInitCommand", () => {
expect(output.messages.join("\n")).not.toContain("Overrode package.json engines.node");
});
+ it("adds an agent to an existing project with model settings selected by init options", async () => {
+ const parentDirectory = await mkdtemp(join(tmpdir(), "eve-init-dir-model-"));
+ const projectRoot = await createHostProject(parentDirectory);
+ const output = logger();
+ const deps = dependencies();
+
+ await runInitCommand(
+ output,
+ parentDirectory,
+ "host-app",
+ { model: "openai/gpt-5.5", reasoning: "high" },
+ deps,
+ );
+
+ const agentSource = await readFile(join(projectRoot, "agent/agent.ts"), "utf8");
+ expect(agentSource).toContain('model: "openai/gpt-5.5"');
+ expect(agentSource).toContain('reasoning: "high"');
+ expect(deps.validateModelSlug).toHaveBeenCalledWith(projectRoot, "openai/gpt-5.5");
+ });
+
it("overrides an incompatible existing node engine declaration and warns for eve init .", async () => {
const parentDirectory = await mkdtemp(join(tmpdir(), "eve-init-dir-engine-"));
const projectRoot = await createHostProject(parentDirectory, {
diff --git a/packages/eve/src/cli/commands/init.ts b/packages/eve/src/cli/commands/init.ts
index 8b89d10e3..fa8615386 100644
--- a/packages/eve/src/cli/commands/init.ts
+++ b/packages/eve/src/cli/commands/init.ts
@@ -10,6 +10,7 @@ import { formatElapsed } from "#cli/format-elapsed.js";
import { startCliLiveRow } from "#cli/ui/live-row.js";
import { createLogger, isLogLevelEnabled } from "#internal/logging.js";
import { DEFAULT_AGENT_MODEL_ID } from "#shared/default-agent-model.js";
+import type { AgentReasoningDefinition } from "#shared/agent-definition.js";
import { formatNodeEngineOverrideWarning, type NodeEngineOverride } from "#setup/node-engine.js";
import {
detectInvokingPackageManager,
@@ -28,6 +29,7 @@ import { addAgentToProject } from "#setup/scaffold/create/add-to-project.js";
import { blockingCreateInPlaceEntries } from "#setup/scaffold/create-in-place.js";
import { ensureChannel, scaffoldBaseProject } from "#setup/scaffold/index.js";
import { WizardCancelledError } from "#setup/step.js";
+import { validateModelSlug } from "#setup/flows/model-source-change.js";
import type { WorkspaceRootMutation } from "#setup/scaffold/workspace-root.js";
import {
DEFAULT_EVE_PACKAGE_CONTRACT,
@@ -50,6 +52,10 @@ export interface InitCliLogger {
export interface InitCommandOptions {
/** Add the Web Chat channel (a Next.js app). Set by `--channel-web-nextjs`. */
channelWebNextjs?: boolean;
+ /** Model id written to the root agent config. Set by `--model`. */
+ model?: string;
+ /** Reasoning effort written to the root agent config. Set by `--reasoning`. */
+ reasoning?: AgentReasoningDefinition;
}
export interface InitCommandDependencies {
@@ -65,6 +71,7 @@ export interface InitCommandDependencies {
spawnCodingAgentRepl: typeof spawnCodingAgentRepl;
spawnPackageManager: typeof spawnPackageManager;
tryInitializeGit: typeof tryInitializeGit;
+ validateModelSlug: typeof validateModelSlug;
}
const defaultDependencies: InitCommandDependencies = {
@@ -80,6 +87,7 @@ const defaultDependencies: InitCommandDependencies = {
spawnCodingAgentRepl,
spawnPackageManager,
tryInitializeGit,
+ validateModelSlug,
};
const CURRENT_DIRECTORY_PROJECT_NAME = ".";
@@ -162,10 +170,16 @@ async function addToExistingProject(
);
}
+ if (options.model !== undefined) {
+ const rejection = await dependencies.validateModelSlug(targetPath, options.model);
+ if (rejection !== null) throw new Error(rejection);
+ }
+
const manager = await dependencies.detectPackageManager(targetPath);
const result = await dependencies.addAgentToProject({
projectRoot: targetPath,
- model: DEFAULT_AGENT_MODEL_ID,
+ model: options.model ?? DEFAULT_AGENT_MODEL_ID,
+ reasoning: options.reasoning,
packageManager: manager.kind,
evePackage,
});
@@ -210,10 +224,15 @@ async function scaffoldProject(
const stagingDirectory = await mkdtemp(join(parentPath, ".eve-init-"));
const workspaceRootMutations: WorkspaceRootMutation[] = [];
try {
+ if (options.model !== undefined) {
+ const rejection = await dependencies.validateModelSlug(stagingDirectory, options.model);
+ if (rejection !== null) throw new Error(rejection);
+ }
const stagedProjectName = createInPlace ? basename(projectPath) : projectName;
const scaffoldOptions = {
projectName: stagedProjectName,
- model: DEFAULT_AGENT_MODEL_ID,
+ model: options.model ?? DEFAULT_AGENT_MODEL_ID,
+ reasoning: options.reasoning,
evePackage,
targetDirectory: stagingDirectory,
workspaceProbeDirectory: projectPath,
diff --git a/packages/eve/src/cli/commands/set.test.ts b/packages/eve/src/cli/commands/set.test.ts
new file mode 100644
index 000000000..3cf0e4de6
--- /dev/null
+++ b/packages/eve/src/cli/commands/set.test.ts
@@ -0,0 +1,164 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { stripAnsi } from "#cli/ui/terminal-text.js";
+
+import { runSetCommand, type SetCommandDependencies } from "./set.js";
+
+function logger() {
+ const errors: string[] = [];
+ const logs: string[] = [];
+ return {
+ errors,
+ logs,
+ error: (message: string) => errors.push(message),
+ log: (message: string) => logs.push(message),
+ };
+}
+
+function dependencies(overrides: Partial<SetCommandDependencies> = {}): SetCommandDependencies {
+ return {
+ changeAgentModelSettings: vi.fn<SetCommandDependencies["changeAgentModelSettings"]>(
+ async () => ({
+ kind: "changed",
+ changed: ["model", "reasoning"],
+ model: "openai/gpt-5.6-sol",
+ reasoning: "high",
+ }),
+ ),
+ isEveProject: vi.fn(async () => true),
+ ...overrides,
+ };
+}
+
+afterEach(() => {
+ process.exitCode = undefined;
+});
+
+describe("runSetCommand", () => {
+ it("updates the model and reasoning through one shared source change", async () => {
+ const output = logger();
+ const deps = dependencies();
+
+ await runSetCommand(
+ output,
+ "/project",
+ { model: "openai/gpt-5.6-sol", reasoning: "high" },
+ deps,
+ );
+
+ expect(deps.changeAgentModelSettings).toHaveBeenCalledWith({
+ appRoot: "/project",
+ patch: {
+ model: { kind: "set", value: "openai/gpt-5.6-sol" },
+ reasoning: { kind: "set", value: "high" },
+ gatewayServiceTier: { kind: "keep" },
+ },
+ });
+ expect(stripAnsi(output.logs.join("\n"))).toContain(
+ "Model settings updated: model openai/gpt-5.6-sol, reasoning high. Live on your next prompt.",
+ );
+ expect(output.errors).toEqual([]);
+ expect(process.exitCode).toBeUndefined();
+ });
+
+ it("updates reasoning without changing the model", async () => {
+ const output = logger();
+ const deps = dependencies();
+
+ await runSetCommand(output, "/project", { reasoning: "low" }, deps);
+
+ expect(deps.changeAgentModelSettings).toHaveBeenCalledWith({
+ appRoot: "/project",
+ patch: {
+ model: { kind: "keep" },
+ reasoning: { kind: "set", value: "low" },
+ gatewayServiceTier: { kind: "keep" },
+ },
+ });
+ });
+
+ it("updates the model without changing reasoning", async () => {
+ const output = logger();
+ const deps = dependencies({
+ changeAgentModelSettings: vi.fn<SetCommandDependencies["changeAgentModelSettings"]>(
+ async () => ({
+ kind: "changed",
+ changed: ["model"],
+ model: "openai/gpt-5.6-sol",
+ }),
+ ),
+ });
+
+ await runSetCommand(output, "/project", { model: "openai/gpt-5.6-sol" }, deps);
+
+ expect(deps.changeAgentModelSettings).toHaveBeenCalledWith({
+ appRoot: "/project",
+ patch: {
+ model: { kind: "set", value: "openai/gpt-5.6-sol" },
+ reasoning: { kind: "keep" },
+ gatewayServiceTier: { kind: "keep" },
+ },
+ });
+ expect(stripAnsi(output.logs.join("\n"))).toContain(
+ "Model changed to openai/gpt-5.6-sol. Live on your next prompt.",
+ );
+ });
+
+ it("removes authored reasoning for the provider default", async () => {
+ const output = logger();
+ const deps = dependencies();
+
+ await runSetCommand(output, "/project", { reasoning: "provider-default" }, deps);
+
+ expect(deps.changeAgentModelSettings).toHaveBeenCalledWith({
+ appRoot: "/project",
+ patch: {
+ model: { kind: "keep" },
+ reasoning: { kind: "remove" },
+ gatewayServiceTier: { kind: "keep" },
+ },
+ });
+ });
+
+ it("requires at least one setting", async () => {
+ const output = logger();
+ const deps = dependencies();
+
+ await runSetCommand(output, "/project", {}, deps);
+
+ expect(deps.changeAgentModelSettings).not.toHaveBeenCalled();
+ expect(output.errors).toEqual(["Pass --model, --reasoning, or both."]);
+ expect(process.exitCode).toBe(1);
+ });
+
+ it("reports source-change rejections as command failures", async () => {
+ const output = logger();
+ const deps = dependencies({
+ changeAgentModelSettings: vi.fn<SetCommandDependencies["changeAgentModelSettings"]>(
+ async () => ({ kind: "rejected", message: "Unknown model." }),
+ ),
+ });
+
+ await runSetCommand(output, "/project", { model: "unknown/model" }, deps);
+
+ expect(output.logs).toEqual([]);
+ expect(output.errors).toEqual(["Unknown model."]);
+ expect(process.exitCode).toBe(1);
+ });
+
+ it("formats source-change errors", async () => {
+ const output = logger();
+ const deps = dependencies({
+ changeAgentModelSettings: vi.fn<SetCommandDependencies["changeAgentModelSettings"]>(
+ async () => {
+ throw new Error("agent.ts could not be read");
+ },
+ ),
+ });
+
+ await runSetCommand(output, "/project", { reasoning: "high" }, deps);
+
+ expect(output.errors).toEqual(["Couldn't update model settings: agent.ts could not be read"]);
+ expect(process.exitCode).toBe(1);
+ });
+});
diff --git a/packages/eve/src/cli/commands/set.ts b/packages/eve/src/cli/commands/set.ts
new file mode 100644
index 000000000..3cca2e61b
--- /dev/null
+++ b/packages/eve/src/cli/commands/set.ts
@@ -0,0 +1,78 @@
+import { isEveProject } from "#setup/scaffold/index.js";
+import {
+ changeAgentModelSettings,
+ formatApplyModelSettingsOutcome,
+ type ApplyModelSettingsOutcome,
+} from "#setup/flows/model-source-change.js";
+import type { AgentReasoningDefinition } from "#shared/agent-definition.js";
+import type { AgentModelSettingsPatch } from "#source-change/apply-agent-model-settings.js";
+
+import { NOT_AN_AGENT_MESSAGE } from "./preconditions.js";
+
+export interface SetCommandLogger {
+ error(message: string): void;
+ log(message: string): void;
+}
+
+export interface SetCommandOptions {
+ model?: string;
+ reasoning?: AgentReasoningDefinition;
+}
+
+export interface SetCommandDependencies {
+ changeAgentModelSettings: (input: {
+ appRoot: string;
+ patch: AgentModelSettingsPatch;
+ }) => Promise<ApplyModelSettingsOutcome>;
+ isEveProject: typeof isEveProject;
+}
+
+const defaultDependencies: SetCommandDependencies = {
+ changeAgentModelSettings,
+ isEveProject,
+};
+
+function fail(logger: SetCommandLogger, message: string): void {
+ logger.error(message);
+ process.exitCode = 1;
+}
+
+export async function runSetCommand(
+ logger: SetCommandLogger,
+ appRoot: string,
+ options: SetCommandOptions,
+ dependencies: SetCommandDependencies = defaultDependencies,
+): Promise<void> {
+ if (options.model === undefined && options.reasoning === undefined) {
+ fail(logger, "Pass --model, --reasoning, or both.");
+ return;
+ }
+
+ if (!(await dependencies.isEveProject(appRoot))) {
+ fail(logger, NOT_AN_AGENT_MESSAGE);
+ return;
+ }
+
+ const patch: AgentModelSettingsPatch = {
+ model: options.model === undefined ? { kind: "keep" } : { kind: "set", value: options.model },
+ reasoning:
+ options.reasoning === undefined
+ ? { kind: "keep" }
+ : options.reasoning === "provider-default"
+ ? { kind: "remove" }
+ : { kind: "set", value: options.reasoning },
+ gatewayServiceTier: { kind: "keep" },
+ };
+
+ try {
+ const outcome = await dependencies.changeAgentModelSettings({ appRoot, patch });
+ if (outcome.kind === "rejected") {
+ fail(logger, outcome.message);
+ return;
+ }
+ logger.log(formatApplyModelSettingsOutcome(outcome));
+ } catch (error) {
+ const message = error instanceof Error ? error.message : String(error);
+ fail(logger, `Couldn't update model settings: ${message}`);
+ }
+}
diff --git a/packages/eve/src/cli/option-parsers.ts b/packages/eve/src/cli/option-parsers.ts
index 290ace447..d0d9053a7 100644
--- a/packages/eve/src/cli/option-parsers.ts
+++ b/packages/eve/src/cli/option-parsers.ts
@@ -1,5 +1,7 @@
import { InvalidArgumentError } from "#compiled/commander/index.js";
import { LOG_DISPLAY_MODES, parseLogDisplayMode } from "#cli/dev/tui/log-display-mode.js";
+import { ALL_REASONING_LEVELS } from "#setup/boxes/model-capabilities.js";
+import type { AgentReasoningDefinition } from "#shared/agent-definition.js";
import type {
AssistantResponseStatsMode,
LogDisplayMode,
@@ -66,3 +68,19 @@ export function parseContextSizeOption(value: string): number {
return size;
}
+
+const REASONING_VALUES: readonly AgentReasoningDefinition[] = [
+ "provider-default",
+ ...ALL_REASONING_LEVELS,
+];
+
+/** Parses an authored model reasoning effort. */
+export function parseReasoningOption(value: string): AgentReasoningDefinition {
+ if (!REASONING_VALUES.some((candidate) => candidate === value)) {
+ throw new InvalidArgumentError(
+ `Expected one of ${REASONING_VALUES.join(", ")}, received "${value}".`,
+ );
+ }
+
+ return value as AgentReasoningDefinition;
+}
diff --git a/packages/eve/src/cli/run.test.ts b/packages/eve/src/cli/run.test.ts
index 1ceeb6252..d7419416f 100644
--- a/packages/eve/src/cli/run.test.ts
+++ b/packages/eve/src/cli/run.test.ts
@@ -7,6 +7,14 @@ import { MockScreen } from "#cli/dev/tui/test/mock-terminal.js";
import type { RunDevelopmentTuiInput } from "#cli/dev/tui/tui.js";
import type { DevelopmentServerOptions } from "#internal/nitro/host/types.js";
+const { runInitCommand, runSetCommand } = vi.hoisted(() => ({
+ runInitCommand: vi.fn(async () => {}),
+ runSetCommand: vi.fn(async () => {}),
+}));
+
+vi.mock("#cli/commands/init.js", () => ({ runInitCommand }));
+vi.mock("#cli/commands/set.js", () => ({ runSetCommand }));
+
async function withInteractiveTerminal<T>(fn: () => Promise<T>): Promise<T> {
const stdinDescriptor = Object.getOwnPropertyDescriptor(process.stdin, "isTTY");
const stdoutDescriptor = Object.getOwnPropertyDescriptor(process.stdout, "isTTY");
@@ -50,12 +58,47 @@ describe("CLI command registration", () => {
const help = output.join("\n");
expect(help).toContain("init [options] [target]");
+ expect(help).toContain("set [options]");
expect(help).toContain("link");
expect(help).toContain("deploy");
expect(help).toContain("registry");
expect(help).not.toContain("setup [options] <item>");
});
+ it("forwards model settings to the set command", async () => {
+ const logger = { error: vi.fn(), log: vi.fn() };
+ runSetCommand.mockClear();
+
+ await runCli(["set", "--model", "openai/gpt-5.6-sol", "--reasoning", "high"], logger);
+
+ expect(runSetCommand).toHaveBeenCalledWith(logger, resolve(process.cwd()), {
+ model: "openai/gpt-5.6-sol",
+ reasoning: "high",
+ });
+ });
+
+ it("lists model and reasoning options for the set command", async () => {
+ const output: string[] = [];
+
+ await runCli(["set", "--help"], {
+ error: (message) => output.push(message),
+ log: (message) => output.push(message),
+ });
+
+ const help = output.join("\n");
+ expect(help).toContain("--model <model>");
+ expect(help).toContain("--reasoning <effort>");
+ });
+
+ it("rejects unsupported reasoning before running the set command", async () => {
+ const logger = { error: vi.fn(), log: vi.fn() };
+ runSetCommand.mockClear();
+
+ await expect(runCli(["set", "--reasoning", "extreme"], logger)).rejects.toThrow();
+
+ expect(runSetCommand).not.toHaveBeenCalled();
+ });
+
it("lists registry installation and setup options", async () => {
const output: string[] = [];
const logger = {
@@ -140,7 +183,7 @@ describe("CLI command registration", () => {
});
describe("eve init compatibility flags", () => {
- it("lists --yes as an accepted compatibility flag", async () => {
+ it("lists the supported init options", async () => {
const output: string[] = [];
await runCli(["init", "--help"], {
@@ -148,7 +191,35 @@ describe("eve init compatibility flags", () => {
log: (message) => output.push(message),
});
- expect(output.join("\n")).toContain("-y, --yes");
+ const help = output.join("\n");
+ expect(help).toContain("-y, --yes");
+ expect(help).toContain("--model <model>");
+ expect(help).toContain("--reasoning <effort>");
+ });
+
+ it("forwards model settings to the init command", async () => {
+ const logger = { error: vi.fn(), log: vi.fn() };
+ runInitCommand.mockClear();
+
+ await runCli(
+ ["init", "my-agent", "--model", "openai/gpt-5.6-sol", "--reasoning", "high"],
+ logger,
+ );
+
+ expect(runInitCommand).toHaveBeenCalledWith(logger, resolve(process.cwd()), "my-agent", {
+ channelWebNextjs: undefined,
+ model: "openai/gpt-5.6-sol",
+ reasoning: "high",
+ });
+ });
+
+ it("rejects unsupported reasoning before running the init command", async () => {
+ const logger = { error: vi.fn(), log: vi.fn() };
+ runInitCommand.mockClear();
+
+ await expect(runCli(["init", "my-agent", "--reasoning", "extreme"], logger)).rejects.toThrow();
+
+ expect(runInitCommand).not.toHaveBeenCalled();
});
it("still rejects unknown init options", async () => {
diff --git a/packages/eve/src/cli/run.ts b/packages/eve/src/cli/run.ts
index ef710fb4c..43af5cd3a 100644
--- a/packages/eve/src/cli/run.ts
+++ b/packages/eve/src/cli/run.ts
@@ -34,8 +34,10 @@ import {
parseDisplayMode,
parseLogsMode,
parsePortOption,
+ parseReasoningOption,
parseStatsMode,
} from "#cli/option-parsers.js";
+import type { AgentReasoningDefinition } from "#shared/agent-definition.js";
import { resolveTuiTitle, type DevelopmentTuiTarget } from "#cli/dev/tui/target.js";
import {
resumeDevelopmentRuntimeArtifacts,
@@ -220,11 +222,22 @@ function createCliProgram(logger: CliLogger, runtime: CliRuntimeOverrides): Comm
.command("init [target]")
.description("Create a new eve agent, or add one to an existing project directory.")
.option("--channel-web-nextjs", "Add the Web Chat application (Next.js)")
+ .option("--model <model>", "Set the agent model (provider/model-id)")
+ .option(
+ "--reasoning <effort>",
+ "Set reasoning (provider-default|none|minimal|low|medium|high|xhigh)",
+ parseReasoningOption,
+ )
.option("-y, --yes", "Accepted for compatibility; has no effect")
.action(
async (
target: string | undefined,
- options: { channelWebNextjs?: boolean; yes?: boolean },
+ options: {
+ channelWebNextjs?: boolean;
+ model?: string;
+ reasoning?: AgentReasoningDefinition;
+ yes?: boolean;
+ },
) => {
if (options.yes) {
logger.error("warning: --yes has no effect for eve init.");
@@ -233,10 +246,26 @@ function createCliProgram(logger: CliLogger, runtime: CliRuntimeOverrides): Comm
const { runInitCommand } = await import("#cli/commands/init.js");
await runInitCommand(logger, appRoot, target, {
channelWebNextjs: options.channelWebNextjs,
+ model: options.model,
+ reasoning: options.reasoning,
});
},
);
+ program
+ .command("set")
+ .description("Change root agent model settings.")
+ .option("--model <model>", "Set the agent model (provider/model-id)")
+ .option(
+ "--reasoning <effort>",
+ "Set reasoning (provider-default|none|minimal|low|medium|high|xhigh)",
+ parseReasoningOption,
+ )
+ .action(async (options: { model?: string; reasoning?: AgentReasoningDefinition }) => {
+ const { runSetCommand } = await import("#cli/commands/set.js");
+ await runSetCommand(logger, appRoot, options);
+ });
+
registerProjectCommands({ program, logger, appRoot });
registerBuildCommand({
diff --git a/packages/eve/src/setup/flows/model-source-change.ts b/packages/eve/src/setup/flows/model-source-change.ts
index 20e369390..ce22d5da4 100644
--- a/packages/eve/src/setup/flows/model-source-change.ts
+++ b/packages/eve/src/setup/flows/model-source-change.ts
@@ -118,7 +118,7 @@ export async function changeAgentModel(input: {
: { kind: "changed", to: result.to };
}
-async function validateModelSlug(appRoot: string, slug: string): Promise<string | null> {
+export async function validateModelSlug(appRoot: string, slug: string): Promise<string | null> {
if (!slug.includes("/")) {
return `\`${slug}\` isn't a provider/model id (e.g. anthropic/claude-sonnet-5).`;
}
diff --git a/packages/eve/src/setup/scaffold/create/add-to-project.ts b/packages/eve/src/setup/scaffold/create/add-to-project.ts
index 6fe79f947..fceae7127 100644
--- a/packages/eve/src/setup/scaffold/create/add-to-project.ts
+++ b/packages/eve/src/setup/scaffold/create/add-to-project.ts
@@ -3,6 +3,7 @@ import { join } from "node:path";
import type { PackageManagerKind } from "../../package-manager.js";
import type { NodeEngineOverride } from "../../node-engine.js";
+import type { AgentReasoningDefinition } from "../../../shared/agent-definition.js";
import { pathExists, writeTextFile } from "../files.js";
import { patchPackageJson, type PackageJsonPatch } from "../update/package-json.js";
import { resolveVersionToken } from "../version-tokens.js";
@@ -24,6 +25,7 @@ import {
export interface AddAgentToProjectOptions {
projectRoot: string;
model: string;
+ reasoning?: AgentReasoningDefinition;
/**
* The host project's package manager, which owns any manager-specific
* generated project configuration. Defaults to pnpm.
@@ -85,7 +87,7 @@ export async function addAgentToProject(
);
}
- const files = agentTemplateFiles(options.model);
+ const files = agentTemplateFiles(options.model, options.reasoning);
const conflicts: string[] = [];
for (const relativePath of Object.keys(files)) {
if (await pathExists(join(options.projectRoot, relativePath))) {
diff --git a/packages/eve/src/setup/scaffold/create/project.ts b/packages/eve/src/setup/scaffold/create/project.ts
index 33fca8972..bad0ddfbe 100644
--- a/packages/eve/src/setup/scaffold/create/project.ts
+++ b/packages/eve/src/setup/scaffold/create/project.ts
@@ -3,6 +3,7 @@ import { basename, join, resolve } from "node:path";
import type { PackageManagerKind } from "../../package-manager.js";
import { pinnedNodeEngineMajor } from "../../node-engine.js";
+import type { AgentReasoningDefinition } from "../../../shared/agent-definition.js";
import { SUPPORTED_AUTHORED_MODULE_FILE_EXTENSIONS } from "../update/module-files.js";
import { pathExists, writeTextFile } from "../files.js";
import { blockingCreateInPlaceEntries } from "../create-in-place.js";
@@ -53,6 +54,7 @@ export function resolveEvePackageContract(
interface TemplateContext {
appName: string;
model: string;
+ reasoning?: AgentReasoningDefinition;
eveVersion: string;
aiPackageVersion: string;
connectPackageVersion: string;
@@ -93,18 +95,31 @@ export function byokProviderEnvVar(modelId: string): string {
* subset `eve init` writes when adding an agent to an existing project, where
* everything outside `agent/` belongs to the host app.
*/
-export function agentTemplateFiles(model: string): Record<string, string> {
+export function agentTemplateFiles(
+ model: string,
+ reasoning?: AgentReasoningDefinition,
+): Record<string, string> {
return {
- "agent/agent.ts": BASE_AGENT_TEMPLATE.replaceAll("__EVE_INIT_MODEL__", model),
+ "agent/agent.ts": BASE_AGENT_TEMPLATE.replaceAll("__EVE_INIT_MODEL__", model).replaceAll(
+ "__EVE_INIT_REASONING__",
+ reasoningTemplateLine(reasoning),
+ ),
"agent/channels/eve.ts": WEB_APP_TEMPLATE_FILES["agent/channels/eve.ts"],
"agent/instructions.md": AGENT_INSTRUCTIONS_TEMPLATE,
};
}
+function reasoningTemplateLine(reasoning: AgentReasoningDefinition | undefined): string {
+ return reasoning === undefined || reasoning === "provider-default"
+ ? ""
+ : ` reasoning: "${reasoning}",\n`;
+}
+
function renderTemplate(content: string, ctx: TemplateContext): string {
return content
.replaceAll("__EVE_INIT_APP_NAME__", ctx.appName)
.replaceAll("__EVE_INIT_MODEL__", ctx.model)
+ .replaceAll("__EVE_INIT_REASONING__", reasoningTemplateLine(ctx.reasoning))
.replaceAll("__EVE_INIT_BYOK_PROVIDER__", modelProviderSlug(ctx.model))
.replaceAll("__EVE_INIT_BYOK_ENV_VAR__", byokProviderEnvVar(ctx.model))
.replaceAll("__EVE_INIT_PACKAGE_VERSION__", formatEveDependencySpecifier(ctx.eveVersion))
@@ -126,7 +141,7 @@ const BASE_AGENT_TEMPLATE = `import { defineAgent } from "eve";
export default defineAgent({
model: "__EVE_INIT_MODEL__",
-});
+__EVE_INIT_REASONING__});
`;
// The agent reaches the model through a provider key the user supplies via the
@@ -139,7 +154,7 @@ const BYOK_AGENT_TEMPLATE = `import { defineAgent } from "eve";
export default defineAgent({
model: "__EVE_INIT_MODEL__",
- modelOptions: {
+__EVE_INIT_REASONING__ modelOptions: {
providerOptions: {
gateway: {
byok: {
@@ -355,6 +370,7 @@ async function assertCanCreateInPlace(
export interface ScaffoldBaseProjectOptions {
projectName: string;
model: string;
+ reasoning?: AgentReasoningDefinition;
/**
* The manager that owns command execution and manager-specific generated
* project files for this scaffold.
@@ -404,6 +420,7 @@ export async function scaffoldBaseProject(options: ScaffoldBaseProjectOptions):
const ctx: TemplateContext = {
appName: basename(targetRoot),
model: options.model,
+ reasoning: options.reasoning,
eveVersion: evePackage.version,
aiPackageVersion: resolveVersionToken(
"aiPackageVersion",