Skip to content
TilloTech Docs

How to use Scout

Install the Scout CLI, complete first-time setup, and load the active team and repository context. For command flags, output contracts, and the working-state snapshot, see the Scout CLI reference.

Before you start

  • Node.js 22 or later.
  • Access to the Tillo AWS SSO session and the private npm registry.
  • Git repositories as direct children of a repository root. Setup uses ~/Code by default. Each discovered repository must contain README.md and be the root of a Git worktree. Scout does not discover nested repositories.

Install Scout

Scout is published as @tillo/scout. Log in to the Tillo AWS session first so pnpm can reach the private npm registry.

Configure npm to use CodeArtifact for the @tillo scope:

sh
aws sso login --sso-session tillo-sso

aws codeartifact login \
  --tool npm \
  --repository tillo-npm \
  --domain tillo \
  --domain-owner 307488140247 \
  --region eu-west-1 \
  --profile internal-services \
  --namespace tillo

Install the CLI globally:

sh
pnpm install @tillo/scout -g

The CodeArtifact authorization token expires after 12 hours. Repeat the AWS login and registry setup when the token expires.

Confirm the install:

sh
scout --version

Most commands require a local Scout configuration. Run scout setup before those commands. scout docs search does not need that configuration.

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

Complete first-time setup

A scope is a named set of one or more repositories. Scout stores scopes in the local developer configuration. One scope is active at a time. Scout uses the active scope for context, index work, and code exploration.

Run the interactive setup flow:

sh
scout setup

The flow asks for:

  1. the repository root;
  2. the active team;
  3. one or more discovered repositories;
  4. a name for the active scope;
  5. whether to create a personal preferences file.

Scout saves the configuration at ~/.config/scout/config.yaml. The scope must contain at least one repository. Scout omits code_directory when you accept the default ~/Code. You can enter an absolute path or a path that starts with ~/. Scout expands the value and saves it as code_directory when it differs from the default.

To replace an existing configuration, pass --force:

sh
scout setup --force

!CAUTION --force replaces the existing local Scout configuration, including saved scopes.

Confirm the setup

Read the active team and scope:

sh
scout context

Scout writes the context to standard output. It writes errors to standard error and returns a non-zero exit code when it cannot resolve the context.

Inspect configuration and scope health:

sh
scout doctor

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

If the context command succeeds, setup is complete. EOS SDLC skills probe Scout before they ask for team or repository context. They continue when Scout is absent or when scout context fails. Scout remains optional, and /ask-eos can help with setup. For the SDLC skill chain, see How to use the AI-enabled SDLC.

Change the active team or scope

Run the team selector:

sh
scout change-team

This command changes the active team and keeps all saved scopes.

Run the scope manager:

sh
scout change-scope

The scope manager can select a saved scope, create a scope, 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.

Press Escape in change-team to cancel without saving. In change-scope, press Escape on the action menu to cancel. Press Escape on another screen to return to the previous screen. A cancelled flow does not save configuration or start indexing.

Record personal preferences

Create or open the personal preferences file:

sh
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.

Write working style, communication, and personal constraints in that file. scout context includes the file contents on every run. Delete the file to turn the feature off.

Search Tillo documentation

Search Tillo documentation for product, engineering, or repository facts:

sh
scout docs search "<query>"

The command needs no setup or authentication. Use a focused query. Refine the query when Scout returns no matches.

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