Skip to content
devsess
Esc
↑↓navigate↵open⌘Jpreview

Writing a dev CLI

devsess doesn’t wrap effect/cli for you — you write a stock Command.make(...), and devsess gives you services and layers that plug into it: a session directory that survives restarts, a sticky port, managed subprocesses, and cross-package running signals.

Building the command

// scripts/dev.ts
import { CurrentSession, DevSessions, getStickyPort, runManagedSubprocess } from 'devsess'
import { NodeRuntime, NodeServices } from '@effect/platform-node'
import { Effect } from 'effect'
import { Command } from 'effect/cli'

const web = Command.make('web', {}, () =>
	Effect.gen(function* () {
		// the interesting part goes here
	}).pipe(Effect.provide(CurrentSession.layer)),
)

Command.run(web, { version: '0.1.0' }).pipe(
	Effect.provide(DevSessions.layer),
	Effect.provide(NodeServices.layer),
	Effect.scoped,
	NodeRuntime.runMain,
)
  • Command.make(name, config, handler) and Command.run(command, { version }) are plain effect/cli — nothing devsess-specific. name shows in --help; config is your flags (see Flags); version is whatever --version should print.
  • DevSessions.layer provides the session store, rooted at your project — see Dev sessions for how that root gets picked.
  • CurrentSession.layer provides the resolved session for this run — but only around the handler, not around Command.run. See below for why.
  • NodeServices.layer (or @effect/platform-bun’s BunServices.layer) supplies the FileSystem/Path/ChildProcessSpawner/etc. devsess and effect/cli need underneath. devsess depends on neither platform package itself — you supply whichever one you run scripts with.
  • Effect.scoped is yours to add — see One scope for the whole run.

Full types are in the API reference.

Why CurrentSession.layer sits on the handler

CurrentSession resolves (or creates) a session via DevSessions#getLatestOrCreate, cached for the run — yield* CurrentSession twice in one handler resolves the identical session both times.

Provide it around each command’s own handler:

const web = Command.make('web', {}, () =>
	myHandler.pipe(Effect.provide(CurrentSession.layer)),
)

not around Command.run:

// don't do this — resolves (and creates) a session for --help too
Command.run(web, { version: '0.1.0' }).pipe(
	Effect.provide(CurrentSession.layer),
	Effect.provide(DevSessions.layer),
	// ...
)

A Layer’s build effect runs the moment it’s provided, regardless of what the effect it wraps ends up doing. Wrapping the whole Command.run call means that build effect runs before argv parsing has even decided whether this invocation is --help, --version, or a bad flag — none of which ever reach a handler. Scoping CurrentSession.layer to the handler is what keeps those from creating a session at all. If you have more than one command, provide it around each handler that needs it.

CurrentSession.layerOf(session) pins an explicit session instead of resolving one — useful in tests.

Flags

Command.make’s second argument takes effect/cli’s Flags directly:

import { CurrentSession } from 'devsess'
import { Effect } from 'effect'
import { Command, Flag } from 'effect/cli'

const web = Command.make(
	'web',
	{
		lite: Flag.Boolean('lite').pipe(
			Flag.withDescription('Use a per-session PGlite database'),
		),
	},
	(opts) =>
		Effect.gen(function* () {
			if (opts.lite) {
				// ...
			}
		}).pipe(Effect.provide(CurrentSession.layer)),
)

Each key in the config becomes a property on the handler’s argument — here, opts.lite.

Dev sessions

A session is a directory that outlives your script. CurrentSession resolves to it, and getStickyPort/SessionState (below) read and write inside it.

DevSessions itself also exposes dir (the resolved project root) and path(relative) (joins onto that root, not into any session) — useful for reaching a project file, like a Drizzle migrations folder, without your own node:path import. See A database per session.

Where a session lives

It lives at <root>/.data/sessions/<slug>/ — <slug> a single generated noun, like walrus or piano, not a name you choose.

  • my-app/
    • .data/
      • sessions/
        • walrus/ — the current session
          • sess.json — sticky port and any SessionState slots
          • pglite/ — a per-session PGlite database directory
        • piano/ — an older session, now idle
      • running.json — cross-package signal, not session-scoped
    • scripts/
      • dev.ts

<root> is whatever DevSessions.layer resolved. It walks up from process.cwd() to the nearest ancestor containing a package.json — in a monorepo, running your script from apps/web resolves to apps/web, not the repo root. If no ancestor has one, it fails with ProjectRootNotFoundError (naming the directory it started the search from) instead of silently falling back to process.cwd() — a wrong root means sessions get written somewhere surprising. Pass an explicit root instead with DevSessions.layerAt(rootDir) if you don’t want auto-detection.

How a session gets picked

Every resolution of CurrentSession tries to reuse the last session — the one most recently touched — or creates a new one with a random slug if none exist yet. There’s no flag to choose a specific session: whichever one you touched last is the one you get.

That’s enough for isolation. Every checkout — every git worktree — auto-detects its own root, so its own .data/sessions/ tree. Two agents working in two worktrees never draw from the same pool of sessions, so they never collide: each gets its own port, its own database. Isolation comes from running two different checkouts, not from any session-switching feature inside devsess.

You can create more sessions yourself with DevSessions#createSession, but CurrentSession still always resolves the newest one. An idle session, like piano above, just waits until it happens to become the newest again.

What lives inside a session

SessionState.slot(schema) gives you { read(session), write(session, data) } for a schema you define. Every slot — yours and the library’s own — reads and writes the same file: <session>/sess.json. write shallow-merges your data into whatever’s already there, so distinct slots coexist as long as their keys don’t collide. If two slots use the same key, whichever writes last wins, silently.

import { CurrentSession, SessionState } from 'devsess'
import { Schema } from 'effect'

const LastBranch = SessionState.slot(Schema.Struct({ branch: Schema.String }))

// inside a handler, with CurrentSession.layer provided:
const session = yield* CurrentSession
const state = yield* LastBranch.read(session)
// { branch: string } | null
yield* LastBranch.write(session, { branch: 'main' })

read resolves to T | null, not an Option. null covers two different cases — the file doesn’t exist yet, or it exists but fails to decode against your schema — so treat it as “nothing usable here,” not as “definitely missing.”

Running signals — the mechanism behind publishRunning/awaitRunning — aren’t part of a session at all. They read and write a file scoped to the project root (DevSessions#dir), not any session directory, so a fresh session doesn’t reset them. See Wiring services together.

One scope for the whole run

runManagedSubprocess and publishRunning both register cleanup — “kill this child,” “delete this signal file” — against whatever scope is open when they run. Effect.scoped opens one; wrap it around Command.run(...) itself, not around an individual handler, so every command shares the same scope for as long as the process is alive.

A scope is a lifetime. Effects can register a release action against it — “run this when the scope closes” — and the scope guarantees that release runs exactly once, whether the effect inside finishes normally, fails, or gets interrupted (your Ctrl-C). Put Effect.scoped around the outermost pipeline and it stays open for as long as your script is alive; put it around just a handler instead and cleanup fires the moment that one handler returns, not when the process actually exits.

That’s the mechanism behind two other pages: Running your dev server registers “kill this child” against this scope, and Wiring services together registers “delete this signal file” the same way. Neither depends on your handler doing cleanup itself — the scope closing does it, on a normal exit, a thrown error, or Ctrl-C alike.

Gotchas

session.path(rel) doesn’t create the directory. It resolves a path inside the session and returns it as an Effect<string> — pure path math, no directory or file gets created as a side effect.

import { CurrentSession } from 'devsess'
import { FileSystem } from 'effect/FileSystem'

// inside a handler
const session = yield* CurrentSession
const fs = yield* FileSystem

const dir = yield* session.path('pglite')
// '/my-app/.data/sessions/walrus/pglite'

yield* fs.makeDirectory(dir, { recursive: true })

Skip the makeDirectory call and anything that assumes the path already exists on disk — writing a file under it, pointing a subprocess at it — fails.

“Most recently touched” is filesystem mtime, not a bookkeeping record. There’s no separate “last active” field. A subprocess writing into the directory, a SessionState.write call, anything that touches the session directory refreshes its mtime and keeps it the one CurrentSession resolves next.

SessionState.write isn’t atomic. There’s no temp-file-and-rename step. A sess.json corrupted mid-write makes the next write fail with a SessionStateError (devsess’s tagged error for unparseable session state) — read keeps degrading the same corruption to null instead.

Was this page helpful?