cli

Documentation

Overview

Package cli wires tape's commands. Every command speaks two dialects: human-readable output by default, and a single stable JSON object with --json (schema_version included) for agents and scripts.

Index

• Constants
• Variables
• func Execute(app *App) int
• type App
  • func (a *App) Archive() *local.Archive
  • func (a *App) Close()
  • func (a *App) Defaults() config.Defaults
  • func (a *App) Index() (ports.Index, error)
• type Progress
  • func (p *Progress) Done(msg string)
  • func (p *Progress) Inc(note string)
  • func (p *Progress) SetTotal(n int64)
  • func (p *Progress) Update(n int64, note string)

Constants

const (
	ExitOK        = 0
	ExitError     = 1
	ExitUsage     = 2
	ExitNoResults = 3
	// ExitConflicts: a multi-item operation (today: `tape import`)
	// finished but some items were left unmerged because a conflict
	// could not be resolved automatically (default on non-TTY).
	// Distinct from ExitError so CI scripts can branch on
	// "needs human" without losing the "succeeded for the rest" signal.
	ExitConflicts = 4
	ExitDryRunOK  = 10
)

Variables

var ErrImportConflicts = errors.New("import: unresolved conflicts")

ErrImportConflicts is returned from `tape import` when one or more sessions in the bundle were skipped because we couldn't resolve the conflict automatically. Wrapping with cliError + errors.Is keeps the human-facing message customizable while still mapping to exit code 4.

var ErrNoResults = errors.New("no results")

ErrNoResults maps to exit code 3 so agents can branch on "found nothing" without parsing output.

Functions

func Execute

func Execute(app *App) int

Types

type App

type App struct {
	Sources []ports.Source
	// SourceFactory builds the source set for any home directory; used to
	// parse SSH-mirrored remote homes with the same parsers.
	SourceFactory func(home string) []ports.Source
	Version       string
	// contains filtered or unexported fields
}

App holds process-wide state for a single CLI invocation.

home is where tape stores its own state (archive + index). Users almost never need to think about it; the default ~/.tape is right for everyone who does not multi-tenant. We deliberately do NOT expose it as a flag because it has nothing to do with the project the user is working on — the flag `--dir` in ls/search refers to the project directory instead, matching the user's mental model ("I want my sessions for this repo"). To relocate the archive, set TAPE_HOME=/somewhere/else.

func (*App) Archive

func (a *App) Archive() *local.Archive

func (*App) Close

func (a *App) Close()

func (*App) Defaults

func (a *App) Defaults() config.Defaults

Defaults returns the user's persisted preferences from ~/.tape/config.json. We cache after the first read so commands can call it freely without thinking about I/O. A bad file is reported through debugf (so --debug surfaces it) but never fails the invocation; users editing config in vim shouldn't be able to brick `tape ls`.

func (*App) Index

func (a *App) Index() (ports.Index, error)

type Progress

type Progress struct {
	// contains filtered or unexported fields
}

Progress is a TTY-aware status line. On a TTY it renders a colored bar that overwrites itself in place; on a pipe or with NO_COLOR it stays silent so logs and agent stdout remain clean.

Usage:

pb := app.newProgress("syncing", 0) // unknown total -> spinner mode
pb.SetTotal(123)
pb.Update(7, "claude-code/abc")
pb.Done("synced 123 session(s)")

func (*Progress) Done

func (p *Progress) Done(msg string)

Done clears the bar and prints a final message on its own line.

func (*Progress) Inc

func (p *Progress) Inc(note string)

Inc is shorthand for current++.

func (*Progress) SetTotal

func (p *Progress) SetTotal(n int64)

SetTotal updates the denominator (0 = indeterminate / spinner mode).

func (*Progress) Update

func (p *Progress) Update(n int64, note string)

Update sets current progress and an optional note (e.g. current file).