Scout CLI

Scout is the @tillo/scout command-line interface. It loads the active team, active repository scope, and optional personal preferences. It also indexes active-scope repositories and queries CodeGraph.

For install and first setup, see How to use Scout.

Scout requires Node.js 22 or later. Most commands require a local configuration at ~/.config/scout/config.yaml. scout docs search does not.

Pass --verbose on any command to print the runtime stack trace when the command fails.

Commands

scout setup

scout setup [--force] [--source github|local] [--branch <branch>] [--path <path>]

--path with --source github fails. --branch other than main with --source local fails. An unknown --source value fails.

The command writes ~/.config/scout/config.yaml. The active scope must contain at least one repository. Scout omits code_directory when the repository root is the default ~/Code.

On success the command prints Setup complete. A cancelled interactive flow exits without saving.

scout change-team

scout change-team

The command changes the active team and keeps all saved scopes. On success it prints Active team updated. A cancelled flow does not save configuration.

scout change-scope

scout change-scope

The command can select a saved scope, create a scope from discovered repositories, edit a saved scope, or delete a scope. A scope must contain at least one repository. If the active scope changes, Scout indexes the new scope before it saves the configuration.

Deleting a scope also deletes its working-state snapshot. Cleanup succeeds when the snapshot does not exist.

On success the command prints Active scope updated. A cancelled flow does not save configuration or start indexing.

scout preferences

scout preferences

The command requires a local Scout configuration. It writes ~/.config/scout/preferences.md when the file is missing. It leaves an existing file unchanged. Delete the file to turn the feature off.

scout context

scout context

Returns the active team and active scope as Markdown on standard output. The output includes the active team description, tracker instructions, domain information, labels, active scope, and repository paths. It also includes personal preferences when ~/.config/scout/preferences.md exists. It does not return saved scopes that are not active.

If a working-state snapshot exists for the active scope, Scout appends that Markdown after the preferences section. Scout reads the snapshot as-is and does not parse or rewrite its headings.

Scout writes errors to standard error and returns a non-zero exit code when it cannot resolve the context. A working-state read failure keeps the rest of the context available and writes a warning to standard error.

scout docs search

scout docs search "<query>"

Sends one free-text query to the built-in EOS Docs MCP server. The command needs no setup or authentication. It returns JSON with relevant text and source links.

Do not send secrets, customer data, or personal data.

scout repos

scout repos [--json]

Lists repositories in the active scope. The output includes each repository name, absolute path, README.md path, documentation path, and ADR path. The command does not list every repository that Scout discovers below the configured repository root.

--json defaults to false. Use it when a script or AI agent needs structured output.

scout locate

scout locate <repository-name>

Returns the absolute path for one repository in the active scope, followed by a newline. The command returns a non-zero exit code when the repository is not in the active scope.

scout status

scout status

Reads local Git tracking data for every repository in the active scope. The output reports each repository name, path, branch, upstream, commits ahead, and commits behind.

A repository is marked unavailable when the local path is missing, HEAD is detached, no upstream branch is set, the repository has no commits, or Git cannot be read. Other repositories in the scope still appear in the output.

scout index

scout index

Builds or updates the CodeGraph index for every repository in the active scope. The command attempts every repository. It reports failures on standard error and returns a non-zero exit code if any repository fails.

scout explore

scout explore "<question>" [--repo <repository-name>]

Returns broad code context as JSON. --repo limits the search to one repository in the active scope.

{
  "question": "Where does checkout validate payment status?",
  "results": [
    {
      "repository": "eos",
      "context": "<CodeGraph explore output>"
    }
  ]
}

The command keeps the CodeGraph output inside context. It preserves newlines, indentation, fences, and headings. The command fails if a target repository is unavailable or has no CodeGraph index. Scout does not return partial explore context.

scout graph

scout graph callers <symbol> --json
scout graph callees <symbol> --json
scout graph impact <symbol> [--depth <n>] [--repo <repository-name>] --json
scout graph affected <file>... [--depth <n>] [--repo <repository-name>] --json

Graph commands write JSON only. --json defaults to true. A --json false value fails with Graph commands support JSON output only.

--depth is available on impact and affected only. Depth must be an integer of at least 1. When --depth is absent, Scout keeps the CodeGraph defaults: impact depth 2 and affected depth 5.

--repo limits a query to one repository in the active scope. Use an exact symbol and --repo when you use a larger impact depth.

The response includes the query and a results array. Each result contains repository and result. The result value contains the CodeGraph output. Scout keeps the active scope order when a query includes multiple repositories.

Graph commands fail when a target repository is unavailable or has no CodeGraph index. They write no partial JSON. Raw codegraph commands are not part of the Scout interface.

scout doctor

scout doctor

Inspects the developer configuration, saved scopes, discovered repositories, documentation paths, ADR paths, and CodeGraph indexes.

The command returns a non-zero exit code for invalid configuration or invalid scope repositories. Missing documentation directories, ADR directories, or CodeGraph indexes produce warnings.

Working-state snapshot

Scout stores a machine-local working-state snapshot for the active scope at:

~/.config/scout/working-state/<active-scope>.md

The scope name must use lowercase kebab-case. The file must not exceed 64 KiB. scout context includes the file after the preferences section when it exists.

An agent can use the snapshot to pass task context to a later session. Before an agent session stops, the agent compares the existing snapshot with the current values for Ticket, Goal, Last step, Next step, and Blockers.

If one value changed, or no snapshot exists, the agent creates the directory and replaces the file with:

# Working state

- Updated: <current ISO-8601 datetime>
- Ticket: <ticket ID or none>

## Goal

<intended outcome>

## Last step

<last completed step>

## Next step

<next planned step>

## Blockers

<current blockers>

The agent does not write a new snapshot when the five values are unchanged. The agent does not add a Status field or include a full transcript. The agent removes the snapshot when the active work ends.

Related documentation

• How to use Scout