# INSIDE visitor CLI

Create named test visitors from the command line, record page views and continue the same identity in a browser.

*Release 3.3 · developer*

## What it is

The **INSIDE visitor CLI** lets you create a test visitor without opening a browser. You can record page views, exchange test chat messages and inspect received events. A saved profile also lets you continue the visitor identity in a browser.

## Who uses it and why

Developers use it to repeat visitor integration tests and inspect the resulting live events. Separate named profiles let you keep test identities apart.

## Where to find it

This is a command-line tool with no INSIDE Settings entry. Ask Powerfront for the tool and the connection details appropriate to your test environment. Use `inside-visitor help` to view its commands.

## How it works

1. Use `session start` with a profile name, test service address and account. A new profile needs an account.
2. Use `view` with the profile and an absolute page address. Recording a view establishes tracking context and opens the live visitor connection.
3. Use `events poll` to retrieve captured events, or `events wait` to wait for a matching event. An event cursor lets you request events after a previous result.
4. Use `chat start`, `chat send` and `chat stop` to exercise a test conversation once the live connection is ready.
5. Use `session stop` to disconnect while keeping the profile, or `session delete` to remove its local saved state.

To continue in a browser, use `browser restore` or its alias `browser handoff`. Supply a suitable same-origin test page through `--path`. Open the returned bootstrap link first, then the returned browser page, and complete that page's cookie consent flow. Creating the handoff disconnects the command-line visitor.

## Configure it

Use `--profile` to select a named visitor, `--base-url` for the test service address and `--account` for the account. The default profile name is `default`. Set an explicit service address for your environment.

Page views can include a type, name, category, product details, referrer, tags, custom data, subsite and language. `--json` requests structured output for automation. `--new` discards the selected profile's existing local state before starting it again.

The local background service starts automatically for commands other than `daemon status`. Use `daemon stop` to stop it. Profiles normally use local application storage; `INSIDE_VISITOR_HOME` selects another storage location.

## Limits and good to know

- Profile names accept 1 to 80 letters, digits, full stops, underscores or hyphens.
- Each profile retains at most 2,000 captured events. Polling returns between 1 and 1,000 events; waits accept 1 to 300 seconds.
- HTTP requests and the initial live connection wait have 30-second timeouts.
- Stopping a session keeps its saved identity. Deleting a profile removes local state, not server-side visitor history.
- `events clear` clears the local capture, not server-side activity.
- Browser restore needs a previously recorded view. Its bootstrap link contains visitor identity and must be kept private.
- `--insecure` accepts invalid certificates and is saved with the profile. Use it only for an appropriate test environment.

## Depends on and works with

### This feature uses

- **Requires** [Visitor identity](VIS-001.md): Profiles retain the visitor identity used by tracking and browser restore.
- **Requires** [Visitor page and product tracking](VIS-003.md): Recording a page view creates the tracking context used for a live test connection.
- **Requires** [Visitor connection recovery](VIS-022.md): The test visitor receives updates through the existing live visitor connection.
- **Works better with** [Starting, ending and expiring chats](CHAT-001.md): CLI chat commands exercise conversation start and stop behaviour.
- **Works better with** [Messages and rich content](CHAT-002.md): CLI chat commands can send visitor messages.

## FAQ and troubleshooting

### Why does session start not put a visitor on the floor?

Session start configures the profile. Record a page view to establish tracking and the live connection.

### Why can I not send a chat message?

Record a page view and establish the live connection first, then start a chat before sending further messages.

### Why can I not create a browser handoff?

The profile must have a visitor identity from a recorded page view. Choose a browser destination on the same origin as the configured test service.

### Does deleting the profile delete the customer's information in INSIDE?

No. It deletes the local test profile. Server-side deletion is a separate operation.