Quickstart

Get a Pathvela agent answering in about two minutes. Pick the surface you want.

Option A — the CLI

1. Install it.

curl -fsSL https://agent.pathvela.com/install.sh | sh

On Windows, use irm https://agent.pathvela.com/install.ps1 | iex.

2. Store your API key. Sign in at platform.pathvela.com and mint a key (see Your Pathvela account), then:

lily key set sk-lily-...
lily key status

lily key status confirms the key is stored and reports your account and remaining balance, so you know you're authenticated before spending anything.

3. Ask something. Run the agent from inside a project folder:

lily run "What files are in this folder and what does this project do?"

The agent looks at your current folder, reads the files it needs, and prints an answer — something like:

This is a Node service. The entry point is src/server.ts, which starts an
Express app on PORT (default 3000). Routes live in src/routes/, and data
access is in src/db/. Tests run with `npm test` (Vitest).

Because it's a full agent, not a search, it can go further — ask it to make a change ("add a health-check route and a test for it") and it will edit the files and run the tests.

Or open the full terminal UI for a back-and-forth session:

lily

On first launch it walks you through signing in if you haven't set a key yet. That's it — the agent is running locally, working in your current folder. To let your Pathvela browser tab or app drive the agent on your machine, install it as a background service with lily bridge install — see Auto mode.

Option B — the SDK

1. Add the package.

npm install @poolot/lily-web

2. Create an agent and run it.

import { createLilyAgent } from '@poolot/lily-web'

const agent = await createLilyAgent({
  apiKey: process.env.POOLOT_API_KEY, // or a signed-in user token
  model: 'poolot-standard',
})

const result = await agent.runDetailed([
  { role: 'user', content: 'Give me three names for a note-taking app.' },
])

console.log(result.outputText)
console.log(result.usage) // { inputTokens, outputTokens, cachedInputTokens, calls }

You'll see something like:

1. Jotly  2. Margin  3. Inkling
{ inputTokens: 24, outputTokens: 18, cachedInputTokens: 0, calls: 1 }

createLilyAgent is async and resolves to an agent handle. runDetailed returns the full result — the text, the status, token usage, and the message history. If you only want the text, agent.run(messages) returns it directly.

3. Stream it into a UI. For a chat-style experience, stream tokens as they arrive:

await agent.runStreaming(
  [{ role: 'user', content: 'Explain WebAssembly in one paragraph.' }],
  (token) => process.stdout.write(token),
  (event) => {
    if (event.type === 'tool_call') console.log('\n[calling', event.name, ']')
  },
)

What just happened

In both cases you talked to the same Pathvela agent and the same poolot-standard model, metered on your account. From here: