# INSIDE operator CLI

The operator command-line tool keeps a named operator session and live connection available between commands.

*Release 3.3 · developer*

## What it is

The **INSIDE operator CLI** lets you sign in from a terminal and reuse that operator session across commands. A local background process keeps the live connection open after a command finishes. Named profiles let you keep separate INSIDE addresses and operator sessions.

## Who uses it and why

Developers use it for authenticated integration checks and command-line work under an operator's identity. The connection is a live operator session and can affect that operator's presence in INSIDE.

## Where to find it

Use the `inside-operator` command in a terminal. `inside-operator help` lists the commands and options. Ask Powerfront for the appropriate CLI package and INSIDE address; there is no **Settings** screen for managing local profiles.

## How it works

1. Run `inside-operator session login`, supplying `--base-url` with your INSIDE address and `--profile` with a local name. `session start` is an alias for the same command.
2. Supply the operator email with `--username` or enter it when prompted. The password prompt does not echo what you type. If required, enter the second-factor code or supply it with `--code`.
3. The CLI saves the session in encrypted local storage and starts its background process automatically. That process maintains the live operator connection.
4. Use `session status --profile NAME` to check a profile or `session list` to list saved profiles and active local connections.

Status distinguishes the transport connection, INSIDE's confirmation of the operator session and authorisation of a validation request. A saved session alone does not establish a working connection. The initial connection waits up to 15 seconds for INSIDE to confirm or reject it.

Use the following commands with the relevant `--profile` when finishing work:

| Command | Effect |
|---|---|
| `session stop` | Disconnects the live connection and keeps the saved session. A later command can reconnect. |
| `session logout` | Attempts server sign-out, clears the saved local session and disconnects. |
| `session delete` | Disconnects and removes the local profile. It does not request server sign-out. |
| `daemon stop` | Stops the background process and the live connections it manages. Saved profiles remain. |

## Configure it

Profile names contain 1 to 80 letters, digits, periods, underscores or hyphens. Without `--profile`, the CLI uses `default`. Set the INSIDE address explicitly on first login. It must be an HTTP or HTTPS address without embedded credentials; the profile retains its origin rather than a page path.

For non-interactive password input, use `--password-stdin`. You can also supply `INSIDE_OPERATOR_EMAIL` and `INSIDE_OPERATOR_PASSWORD` through the process environment. Use `INSIDE_OPERATOR_ENV_FILE` to select an environment file; existing process environment values take precedence over its contents.

Use `INSIDE_OPERATOR_HOME` to choose a separate local storage location. Otherwise, profiles are stored in the operating system's local application-data area, outside the project. On Windows, encrypted sessions are tied to the Windows user. On other systems, a local encryption key protects them.

Certificate validation is enabled unless `--insecure` is selected. That option is retained by the profile and is intended for trusted local development certificates.

## Limits and good to know

- The CLI needs a WebSocket connection for its live operator session.
- Connection recovery is automatic. After a connection failure, matching configured environment credentials can also allow automatic sign-in again.
- Accounts requiring browser-based single sign-on cannot complete that flow through the password login command.
- **Status** checks can reconnect the profile; they are not just a display of saved information. `daemon status` only checks the local background process.
- A status command can succeed while its validation result reports that access is denied. Check both connection and authorisation results. Use `--path` with an appropriate permitted validation operation when needed.
- Logout clears the local session even when server sign-out cannot be reached. Check the reported server status if remote sign-out matters.
- Session encryption does not make a saved profile indefinitely valid or portable to another machine.

## Depends on and works with

### This feature uses

- **Requires** [Login and email verification](SEC-001.md): The CLI signs in using an operator account.
- **Requires** [Logout and remembered computers](SEC-004.md): Saved CLI authentication uses a native operator session and remains subject to session validity.
- **Configured in** [Two-factor authentication for operator sign-in](SEC-003.md): The account's second-factor requirements apply to CLI sign-in.
- **Works better with** [Operator CLI requests and browser login](EXT-024.md): A connected profile can make authenticated requests, invoke hub operations and hand sign-in over to a browser.

### Used by

- **Required by** [Operator CLI requests and browser login](EXT-024.md): Requests and browser login use a saved operator CLI profile; API and hub commands also ensure a live connection.

## FAQ and troubleshooting

### Why is the daemon running but my operator is not connected?

Daemon status only confirms the local process is available. Check the named profile with `session status`, including INSIDE's session confirmation and the last connection error.

### Why does status report access denied after a successful login?

The validation operation may require access your operator does not have. Check the connection state separately and select a permitted validation path with Powerfront's guidance.

### Why did a stopped session reconnect?

Stopping preserves its saved authentication. A later status check, API request or hub invocation can reconnect it. Use `session logout` to clear local authentication.

### Does deleting a profile sign me out on the server?

No. It removes local state and disconnects. Use `session logout` first when you need to attempt server sign-out.

### Why can I not use a saved profile under another Windows account?

Windows session encryption is tied to the user who saved it. Sign in again under the account that will run the CLI.

### Why does automated login fail when verification is required?

Interactive use can prompt for a second-factor code. Non-interactive use must supply the required input explicitly. Browser-based single sign-on still needs a browser flow.