setup-lw

name	setup-lw
description	Set up and troubleshoot the LangWatch CLI, covering login (cloud and self-hosted), endpoint configuration, project selection, and connection problems. Use when the CLI isn't authenticated, can't reach LangWatch, or talks to the wrong project.
license	MIT
compatibility	Requires the `langwatch` CLI (`npm install -g langwatch` or `npx langwatch`). Works with any coding agent.
metadata	{"category":"recipe"}

Set Up the LangWatch CLI

Get the CLI authenticated and talking to the right LangWatch project, then verify. The troubleshooting table at the end covers the common failure modes.

Step 1: Credentials

IMPORTANT: You will need a LangWatch API key. Check whether LANGWATCH_API_KEY is already set: in the process environment, which is where CI injects it, and otherwise in the project's .env file. Use that key instead of asking for a new one. Read LANGWATCH_ENDPOINT from the same places, and nothing else out of .env: if the endpoint is set, the project is on a self-hosted instance, and the CLI works against that endpoint instead of app.langwatch.ai.

For CI and agents, configure non-interactively, and never block on a browser. Have the runner inject the key from your secret store into LANGWATCH_API_KEY, which is what the CLI reads:

# GitHub Actions; any secret store works the same way
env:
  LANGWATCH_API_KEY: ${{ secrets.LANGWATCH_API_KEY }}
  LANGWATCH_ENDPOINT: https://lw.acme.internal   # self-hosted only; omit for cloud

That variable is the whole of the CI setup: every command resolves the key from the environment, so there is no login call to make. Keep the key off the command line: an argument is readable by every other process on the machine, and in a shell it lands in your history file.

Locally, run plain langwatch login. It asks where you are logging in (cloud or self-hosted) and how you will use LangWatch (AI tools, project SDK key, or both), then finishes in the browser. No credential is ever typed or pasted into the terminal: you pick the project on the approval page and its key comes back to the CLI over the same channel, so none of it reaches your shell history. A project SDK key lands as LANGWATCH_API_KEY in .env in the current directory, so keep .env out of version control; an AI-tools login lands in ~/.langwatch/config.json. langwatch login --device skips the questions and goes straight to that RFC 8628 device flow via company SSO.

langwatch login --api-key <key> writes a key you already hold straight to .env, with no browser and no prompts. It is the only non-interactive way to hand login a key, and the key travels through the process argument list, so it is not how a runner should supply one: with LANGWATCH_API_KEY set the CLI already has the key, and the flag adds nothing but the file. Reach for it when something downstream genuinely needs the key on disk. It rewrites an existing LANGWATCH_API_KEY line rather than adding a second one, which is why it beats appending to .env from a shell: a second line makes the credential ambiguous, and one re-run of an append is all it takes to get one.

langwatch login --project <slug> writes a project's key to .env with no key on the command line either, but it authenticates through an existing device login, so it suits a developer machine or a long-lived agent box rather than a fresh CI runner.

--endpoint https://lw.acme.internal combines with any of these to pin a self-hosted instance. It pins the CLI; your instrumented app reads LANGWATCH_ENDPOINT from the environment, so a self-hosted setup needs both.

Step 2: Endpoint and Project

• Cloud (app.langwatch.ai) needs no endpoint configuration.
• Self-hosted: the endpoint resolves flag > env > config > default. Persist it with langwatch config set endpoint https://lw.acme.internal, or export LANGWATCH_ENDPOINT per shell.
• Project: the API key determines the project. Check you're in the right one:

langwatch projects list -o json

A personal access token (PAT) instead of a project key also needs LANGWATCH_PROJECT_ID set.

Step 3: Verify

langwatch whoami          # device-session identity (governance plane)
langwatch status          # resource counts: proves auth + endpoint + project in one shot

langwatch status printing resource counts means the setup is done. Everything else (traces, evaluations, scenarios) builds on this.

Step 4: Discover What You Can Do

Use langwatch docs <path> to read documentation as Markdown. Some useful entry points:

langwatch docs                                    # Docs index
langwatch docs integration/python/guide           # Python integration
langwatch docs integration/typescript/guide       # TypeScript integration
langwatch docs prompt-management/cli              # Prompts CLI
langwatch scenario-docs                           # Scenario docs index

Discover commands with langwatch --help and langwatch <subcommand> --help. List and get commands accept --format json for machine-readable output. Every list command takes --limit <n> to cap the rows and --jq <expr> to read part of the answer. A paginated list answers with an envelope, so count its rows through the row array (--jq '.traces | length'), and read how many there are in all at .pagination.total. Bare --jq length counts the fields of the envelope, not the rows. Read the docs first instead of guessing SDK APIs or CLI flags.

If no shell is available, fetch the same Markdown over plain HTTP. Append .md to any docs path (e.g. https://langwatch.ai/docs/integration/python/guide.md). Index: https://langwatch.ai/docs/llms.txt. Scenario index: https://langwatch.ai/scenario/llms.txt

If anything fails or confuses you while following this skill (broken commands, docs that do not match reality, errors you had to work around), ask the user for permission and run npx --yes langwatch report --user-approved with a --title and --summary (or --session <transcript.jsonl>) to send it to the LangWatch team, and it directly shapes what gets fixed. No login or API key needed. Nothing is sent without --user-approved, and --dry-run prints the exact payload without sending anything. The title, summary and transcript are scrubbed locally first, by pattern: secrets and API keys, plus email addresses, phone numbers, card numbers and public IPv4 addresses. Anything no pattern matches is sent as written, including a contact address passed with --email. With --session, always run --dry-run first and let the user read the payload, because a transcript carries content they never reviewed. npx --yes langwatch report --help explains the options.

Troubleshooting

Symptom	Likely cause	Fix
401 / unauthorized on every command	Wrong, revoked, or missing API key	Re-run langwatch login; check LANGWATCH_API_KEY in .env and the shell (shell wins)
401 with a PAT	Missing project id	export LANGWATCH_PROJECT_ID=<your-project-id>
Connection refused / DNS errors	Self-hosted endpoint wrong or unreachable	Check langwatch config get endpoint and LANGWATCH_ENDPOINT; verify the instance URL loads in a browser from this machine
Right credentials, wrong data	Talking to the wrong project or instance	langwatch projects list; re-login with a key from the intended project
Old shell ignores new .env	Env vars already exported	Start a new shell, or unset LANGWATCH_API_KEY LANGWATCH_ENDPOINT so .env is re-read
A command hangs waiting for input	Interactive prompt in a non-interactive context	No flag answers prompts globally. Set LANGWATCH_API_KEY so nothing needs login, then pass the flag that command takes: --force for prompt tag delete, --force-local or --force-remote for prompt push, -y for logout, skills install, skills uninstall and skills update. -o json only selects an output format; on skills it turns the confirmation into an error rather than a prompt, elsewhere it changes nothing