mastra-pharos

pharos — CLI for Pharos, Mastra's company memory. Ask what happened, who touched it, why, and what's unresolved.

Install

npm install -g mastra-pharos

Requires Node.js >= 22.6.

Usage

pharos login                     authenticate via the Mastra platform
pharos logout                    clear stored credentials
pharos whoami                    show current identity
pharos activity [--window 7d]    active work streams
pharos ask "<question>"          semantic search: evidence + owners
pharos who <topic>               who owns a topic
pharos seek [--q <text>]         raw event timeline: exact-text grep, channel browse
pharos pending                   events ingested but not yet indexed
pharos status                    sync + index health

Start with pharos login — it opens the browser for OAuth against the Mastra platform and stores credentials in ~/.pharos/credentials.json.

Non-interactive (agents, CI): set PHAROS_TOKEN and no browser or credentials file is needed. It takes a Pharos service token (pharos_svc_…, ask an operator) or a platform user token, and always wins over stored credentials.

Examples

pharos activity --window 14d
pharos ask "what broke with tool result persistence?"
pharos who memory
pharos seek --q mastracode --since 1d
pharos seek --channel eng-firehose

Use as Mastra agent tools

The same commands are importable as Mastra tools for any ESM/TypeScript project (@mastra/core is an optional peer dependency — install it alongside):

npm install mastra-pharos @mastra/core

import { Agent } from "@mastra/core/agent";
import { pharosTools } from "mastra-pharos/tools";

export const agent = new Agent({
  id: "company-analyst",
  name: "Company Analyst",
  instructions:
    "Answer questions about what's happening at the company with the pharos tools. " +
    "Start broad (pharos_activity or pharos_ask), then fetch full text for docIds with pharos_show.",
  model: "anthropic/claude-sonnet-4-5",
  tools: pharosTools,
});

Individual tools (pharosAskTool, pharosShowTool, …) are also exported, as is the raw typed API client via mastra-pharos/client.

Auth resolves in this order: a PHAROS_TOKEN env var (for deployed agents and CI, where a browser login is impossible), then the CLI's stored credentials from pharos login.

Publishing (maintainers)

The package ships plain JS built from src/ — Node won't type-strip TS inside node_modules, so prepare compiles to dist/ (it runs automatically on workspace pnpm install and on npm pack/npm publish).

cd packages/cli
npm version patch        # or minor/major
npm publish              # needs npm login with @mastra org publish rights
git push && git push --tags