# EnterSense CLI

`entersense` is a JSON client for the stateless EnterSense v1 developer API. It accepts explicit voice transcripts or normalized motion identifiers and configurable declarative rules. It returns validated intents; it never executes shell commands, opens websites, acquires microphone/camera input, or relays actions to third-party servers.

Voice's production and motion's beta labels describe founder-reported product stages. The available API resolves client-supplied text/gestures; those labels do not certify acquisition hardware, recognition accuracy or an integration. Other senses currently return `sense_unavailable`.

## Install and run

Use the platform binary from the website's versioned downloads. Verify the archive's SHA-256 checksum before extracting it. On macOS/Linux, run `chmod +x entersense`; on Windows use `entersense.exe`. Developer releases also include SDK archives. Package-registry publication is a separate step.

```sh
entersense --version
entersense --help
entersense --url https://YOUR-API-HOST capabilities
entersense --url https://YOUR-API-HOST actions
entersense --url https://YOUR-API-HOST templates
entersense --url https://YOUR-API-HOST validate --file voice-rule.json
entersense --url https://YOUR-API-HOST resolve --file voice-rule.json
```

Provide an HTTP(S) origin or proxy prefix with `--url` or `ENTERSENSE_URL`. No service destination is silently selected. `--timeout` or `ENTERSENSE_TIMEOUT` sets a positive request deadline in seconds (default 10). `--pretty` formats JSON for reading. TLS verification remains enabled. Redirects and HTTP retries are disabled.

`resolve` and `validate` accept `--json '<request>'`, `--file <path>`, or JSON piped to stdin. `--file -` also reads stdin. Inline/file sources are mutually exclusive. JSON input is bounded by the API's 32768-byte v1 limit.

```json
{
  "input": { "sense": "voice", "transcript": "open home" },
  "rules": [
    {
      "id": "home",
      "match": "open home",
      "action": { "type": "navigation.open", "target": "/" }
    }
  ]
}
```

Replace the input with `{"sense":"motion","gesture":"swipe_left"}` and the rule's `match` with `swipe_left` to configure a motion action. Rules can be disabled with `enabled:false`. `minConfidence` only matches when an explicit adapter-supplied input `confidence` meets the threshold; the API does not infer confidence.

The application receives `intents[].action` and explicitly registers the corresponding handler through an SDK. Available action types are `navigation.open`, `text.insert`, `media.play`, `media.pause`, `scene.focus`, and `workflow.trigger`. Workflow actions accept bounded string `parameters`. Navigation targets must be application-relative paths; other targets identify application-owned handlers/resources.

## Automation contract

Successful API JSON goes to stdout. Request/API failures produce structured JSON on stderr. Help/version output is normal CLI text. Exit codes are stable:

| Code | Meaning                                                                |
| ---- | ---------------------------------------------------------------------- |
| 0    | Successful request, including an unmatched resolution; or help/version |
| 2    | Usage, configuration, file/input or JSON error                         |
| 3    | HTTP/API rejection, including unavailable senses and rate limits       |
| 4    | Network, timeout or invalid-response failure                           |

An unmatched resolution is not an execution error. No token is required by the current public stateless API. Never put future credentials in action rules or transcripts. The client does not log request bodies or credential-bearing URLs.

## Development

This is an independent Cargo project with its own lockfile and target directory. It does not modify the web/server workspace.

```sh
cargo fmt --manifest-path cli/Cargo.toml --all --check
cargo clippy --manifest-path cli/Cargo.toml --all-targets -- -D warnings
cargo test --manifest-path cli/Cargo.toml --locked
cargo build --manifest-path cli/Cargo.toml --locked --release
```

The package is `entersense-cli`; `Cargo.toml` defines its source version and `entersense --version` reports the installed executable version. The command adapter uses clap; a framework-independent transport port accepts bounded JSON; reqwest provides the HTTPS adapter. Tests cover request routing, JSON sources, stable errors and transport behavior. API schemas/catalogs are generated by the shared Rust domain, not handwritten here. See [SOURCES.md](SOURCES.md) for toolchain guidance and verification boundaries.

## License

License terms have not yet been published. Public downloads do not grant an open-source license; the source repository remains private.