> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withmethod.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a method

> Run local Codex processes and inspect their results.

# Method SDK

Author a procedure as a YAML `.method`, then run each operation with a fresh Codex process. Method saves its inputs, outputs, checks, changes, and failures.

```sh theme={null}
npm install -g https://app.withmethod.ai/downloads/withmethod-sdk-0.3.0.tgz
method authoring
method get WORKFLOW_ID --out task.method
# Edit the local document.
method validate task.method
method save task.method --reason 'Describe the change.'
method run WORKFLOW_ID --version VERSION_ID
```

Sign-in opens a browser. Credentials stay on the computer. Node.js 22+ and a signed-in Codex CLI are required for Codex execution.

## Authoring

`method authoring all` prints the complete manual. `method COMMAND --help` gives arguments, defaults, output, and errors. The same manual is in [docs/method-authoring.md](/guides/build).

The format uses `format: method/2`, `name`, `goal`, optional `inputs`, `environment`, `state`, a `steps` map, and `result`. A step has `in`, `do` or `ask`, `out`, an optional `check`, and optional `each`, `when`, `after`, `changes`. See [the file example](/method/format).

Author locally and save a complete version. The adjacent `.method.json` keeps its server, method ID, base version, and pending save identity. Keep that file after an upload error and retry the same save.

## Run configuration

`method run` executes a saved version and uploads its records. `method run FILE` executes a local file.

* `--workspace DIR`: local working folder.
* `--inputs FILE`: JSON object of named input values. Defaults come from the method.
* `--resources FILE`: JSON object keyed by environment names, with `{description, path?}`. No secrets.
* `--state-dir DIR`: persistent data folder. Online methods default to `<workspace>/.method/data/<method ID>`; local files default to `<workspace>/.method/data`.
* `--run-dir DIR`: directory for this run's records.
* `--concurrency N`: maximum concurrent operations, default 4.
* `--timeout-ms N`: process time limit, default 300000.
* `--model MODEL`, `--verifier-model MODEL`: Codex models.

Independent steps may run together. Invocations within one `each` currently run in list order. Operations that share a connection or state target run one at a time. A failed operation stops new work while active work finishes.

State reads supply snapshots. State changes return complete new values; the runner validates and writes them. External writes require observations and a separate check. The runner cannot guarantee exactly-once delivery to an external service.

Checks get local input values, returned outputs, and changed targets. They do not get the action conversation. An absent check is recorded as unchecked. A model check can be wrong; its evidence remains available.

## TypeScript

```ts theme={null}
import { loadWorkflow, runWorkflow, CodexExecutor, CodexVerifier } from '@withmethod/sdk';
import { readFileSync } from 'node:fs';
const method = loadWorkflow(readFileSync('task.method', 'utf8'));
const result = await runWorkflow({
  method, inputs: { text: 'Hello\n' }, directory: './runs/example', workspace: '.',
  runtime_revision: 'my-host/1', executor: new CodexExecutor(), verifier: new CodexVerifier(),
});
```

Custom executors implement `execute(request)` and return `{outputs, updates?, observations?, note?}`. Outputs match the step's six-type definitions. File values return `{path}` inside the assigned operation folder; Method computes the hash. `updates` maps declared `state.NAME` targets to full new values. Each external observation has `target`, `status` (`applied`, `not_applied`, `unknown`), and an array of evidence references. Unknown writes stop for inspection.

A verifier implements `verify(request)` and returns `{result, summary, evidence}`. Result is `pass`, `fail`, or `ambiguous`. Pass requires evidence. Custom adapters must honor the time limit and stop their child tools before returning or throwing.

`ask` uses `human.execute(request)`. Return the actual user's `{outputs}` or undefined to pause. The CLI reads those answers from `--human FILE` in `{steps:{INVOCATION:{outputs:{NAME:VALUE}}}}` form.

## Recovery and evidence

A run directory contains the method, inputs, state snapshot, manifest, journal, events, result, and a folder per invocation. Each invocation saves the resolved request, returned candidate, checks, changes, and failure details. Failures record expected behavior, observed behavior, and evidence.

Resume with the same method, inputs, environment, and run directory. Successful invocations are reused. Failed reads need `--retry INVOCATION`. A saved return can be checked again without repeating its write. An uncertain external change needs an inspected `--recoveries FILE`; never run the business action again to determine its outcome. State changed outside a stopped run blocks resume.

`method inspect RUN_DIRECTORY --out inspection.json --include-files` exports records and checked file previews. `method logs RUN_ID` reads dashboard records. `method sync RUN_DIRECTORY` repairs an upload without another business run.

Cloud account setup and browser session transfer are not provided by this local executor.