cli

package
v1.0.0-alpha.14 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 15, 2026 License: MIT Imports: 33 Imported by: 0

Documentation

Overview

Package cli provides internal CLI wiring and command construction for the pulse binary.

Index

Constants

View Source 
const (
	// ExitOK is success. Warnings and advisories ride the envelope (or
	// stderr in text mode) and never move the status.
	ExitOK = 0
	// ExitFatal is a fatal error: under --json the envelope carries
	// it in `errors` (including one escalated by --strict); in text mode
	// it is printed to stderr.
	ExitFatal = 1
	// ExitUsage is a command line refused before any library call: the
	// flag parser's refusals (unknown flag, malformed flag value, missing
	// required flag or argument, mutually exclusive flags) and a bad
	// persistent --log-level / --log-format. No envelope is written.
	ExitUsage = 2
)

The CLI's exit statuses. Scripts branch on these, so they are a contract (docs/src/cli/flags.md "Exit status"): every leaf except `mcp` follows the same three values, with no per-domain codes.

Variables

This section is empty.

Functions

func APICommand 

func APICommand() *cli.Command

APICommand returns the api command group.

func CohortCommand 

func CohortCommand() *cli.Command

CohortCommand returns the cohort command group.

func ConvertCommand 

func ConvertCommand() *cli.Command

ConvertCommand returns the convert command.

func DedupCommand added in v0.39.0 

func DedupCommand() *cli.Command

DedupCommand returns the `pulse dedup` leaf: retro-dedup an EXISTING single-file cohort into a grouped (format 0x02) cohort — the existing-cohort twin of `pulse import <fmt> --group`.

It is its own top-level leaf, beside `pulse widen`, for the reasons widen is: `.pulse` is never a convert SOURCE, so there is no `.pulse` → `.pulse` conversion for it to be a mode of, and an in-place rewrite earns a name a reader cannot mistake for a read. It is not an import mode either — import reads a tabular SOURCE, and the point of retro-dedup is that the source may be gone.

All behaviour is pulse.Dedup; this leaf parses flags, calls it once and formats the report.

func DocsCommand 

func DocsCommand() *cli.Command

DocsCommand returns the `pulse docs` group. Its single leaf, export, is a thin adapter over (*pulse.Pulse).ExportReference: it builds an instance over an in-memory filesystem (no data directory is read, so PULSE_DATA_DIR is not needed), optionally under a feature profile read from a host OS path, and writes the reference to --out on the OS filesystem.

func ErrorsCommand added in v0.5.0 

func ErrorsCommand() *cli.Command

ErrorsCommand returns the errors command group. Two leaves:

  • `pulse errors lookup CODE [--json]`
  • `pulse errors list [--domain D] [--query Q] [--json]`

Both wrap the errors-package lookup surface. CODE detail (Message + Fixup hints) lives behind the lookup tool rather than the bootstrap manifest, so per-session context stays lean.

func ExamplesCommand added in v0.5.0 

func ExamplesCommand() *cli.Command

ExamplesCommand returns the examples command group. Two leaves:

  • `pulse examples search [--query Q] [--tag T] [--category C] [--json]`
  • `pulse examples show NAME [--json]`

Both wrap the embedded request-example library (examples package).

func ExitStatus 

func ExitStatus(err error) (status int, printErr bool)

ExitStatus maps the error app.Run returned to the process exit status, and reports whether main should print the error to stderr (false when the failure is already in the --json envelope on stdout).

func ExplainCommand 

func ExplainCommand() *cli.Command

ExplainCommand returns the `pulse explain` leaf: a request file is described before it runs (predict-checked when it names a cohort), a response file is read into findings — with the request file beside it as its companion.

All behaviour is pulse.Explain; this leaf reads the files, calls it once and formats the result. A response file is decoded with the undefined-figure rule (jsonfinite): a null figure stays undefined instead of reading as 0. A `--json` envelope (format_version + data) is unwrapped to its data.

func ExportCommand 

func ExportCommand() *cli.Command

ExportCommand returns the export command group.

func FeaturesCommand 

func FeaturesCommand() *cli.Command

FeaturesCommand returns the `pulse features` group: thin adapters over the root feature-profile tooling (pulse.InitFeatureProfile, CheckFeatureProfile, DiffFeatureProfile, DescribeFeatureProfile). They describe the binary, not an instance, and hold no logic of their own.

A fatal error exits non-zero on both paths; under --json the envelope is written first, with the error's own code in errors[0].

func ImportCommand 

func ImportCommand() *cli.Command

ImportCommand returns the import command group.

func IndexCommand added in v0.27.0 

func IndexCommand() *cli.Command

IndexCommand returns the `pulse index` command group covering point-lookup sidecar index management: `build`, `list`, `verify`, `drop` — mirroring the `pulse shard` subcommand tree's leaf shape.

func InstallExitPolicy 

func InstallExitPolicy(root *cli.Command) *cli.Command

InstallExitPolicy wires the exit-status contract onto the command tree rooted at root: every command's flag-parser refusals become ExitUsage (the parser's OnUsageError is per command, never inherited, so the whole tree is walked). main owns the status. It returns root for chaining.

func LogBefore 

func LogBefore(ctx context.Context, cmd *cli.Command) (context.Context, error)

LogBefore is the root command's Before: it builds the stderr logger the --log-level / --log-format flags ask for (nil for off) and hands it to every leaf through ctx, where newPulse / newPulseOpts thread it into pulse.Options.Logger. An unknown level or format is CLI_INPUT, and exits ExitUsage.

func LogFlags 

func LogFlags() []cli.Flag

LogFlags returns the root persistent --log-level / --log-format flags. Logs never reach stdout: `--json` output and the `pulse mcp` JSON-RPC transport both depend on a clean stdout.

func MCPCommand added in v0.2.0 

func MCPCommand(version string) *cli.Command

MCPCommand returns the mcp command leaf. Running it serves the MCP protocol over stdio so AI clients (Claude Desktop, Claude Code, etc.) can discover and call Pulse tools. version is the build identity, threaded into both the advertised server Implementation.Version and the adapter Config.

func ProfileCommand added in v0.2.0 

func ProfileCommand() *cli.Command

ProfileCommand returns the `pulse profile` command group.

func RecommendCommand 

func RecommendCommand() *cli.Command

RecommendCommand returns the `pulse recommend` leaf: an intent ID becomes ranked draft requests — placeholder skeletons without --cohort, predict-validated drafts bound to the cohort's fields with it.

All behaviour is pulse.Recommend; this leaf parses flags, calls it once and formats the result.

func SchemaCommand added in v0.23.0 

func SchemaCommand() *cli.Command

SchemaCommand returns the schema command. It prints the bundled JSON Schema (draft 2020-12) describing every public Pulse payload — the request envelopes and the universal output Envelope. The artifact is a self-contained JSON Schema document (it carries its own $schema/$id), so it is emitted raw rather than wrapped in the descriptor Envelope.

This is the offline equivalent of fetching the published file at the $id URL or the pulse://schema MCP resource. CLI is a thin adapter: the schema is the default instance's (Pulse.PayloadSchema), which without a feature profile is the full-registry schema the docs site publishes.

func ShardCommand added in v0.8.0 

func ShardCommand() *cli.Command

ShardCommand returns the `pulse shard` command group covering archive create / add / remove / list / compact / verify / extract. Shard mutations use the atomic temp+rename pattern so partial writes never appear at the canonical archive path.

func SkillsCommand 

func SkillsCommand() *cli.Command

SkillsCommand returns the skills command group.

func SynthCommand added in v0.2.0 

func SynthCommand() *cli.Command

SynthCommand returns the `pulse synth` command group.

func VersionCommand 

func VersionCommand() *cli.Command

VersionCommand returns the `pulse version` leaf. Plain output is `pulse <version>`; --json wraps a VersionInfo in the standard envelope.

func WidenCommand added in v0.38.0 

func WidenCommand() *cli.Command

WidenCommand returns the `pulse widen` leaf: widen one set column of a single-file cohort to a wider set rung, rewriting the cohort in place.

It is its own top-level leaf rather than a mode of `pulse convert` because `.pulse` is reserved on the import side — a legal convert TARGET, never a convert SOURCE (io.Formats()) — so there is no `.pulse` → `.pulse` conversion for a widen to ride on. It is also not a `pulse cohort` subcommand for the same reason `pulse index` is not: this mutates the cohort file itself, and a destructive in-place rewrite earns a name a reader cannot mistake for a read.

All of the behaviour is pulse.WidenSetField: layout dispatch, the refusal policy and the atomic temp/fsync/rename rewrite. This leaf parses three flags, calls it once, and formats the report.

func WriteJSONPublic 

func WriteJSONPublic(w io.Writer, data any) error

WriteJSONPublic is the exported version of writeJSON for use from main.

func WriteManifest 

func WriteManifest(w io.Writer, slim bool, intent string) error

WriteManifest writes the root `pulse --json` envelope: the full manifest, or with intent the manifest scoped to that intent (descx.BuildManifestForIntent over the unprofiled CLI instance), slimmed when slim is set. An unknown intent is a coded error envelope (PULSE_RECOMMEND_INTENT_UNKNOWN), not a manifest.

Types

type DocsExportResult 

type DocsExportResult struct {
	// Out is the --out directory, as given.
	Out string `json:"out"`
	// FeatureProfile is the --feature-profile path, empty for the full
	// default instance.
	FeatureProfile string `json:"feature_profile,omitempty"`
	// Skills reports whether the skill pages were exported.
	Skills bool `json:"skills"`
}

DocsExportResult is the --json data payload of `pulse docs export`.

type VersionInfo 

type VersionInfo struct {
	PulseVersion  string `json:"pulse_version"`
	GoVersion     string `json:"go_version"`
	Commit        string `json:"commit,omitempty"`
	CommitTime    string `json:"commit_time,omitempty"`
	FormatVersion string `json:"format_version"`
}

VersionInfo is the `data` payload of `pulse version --json`. Every field is read from pulse.Version() or the internal/buildinfo helpers; the CLI only assembles them. Commit and CommitTime are omitted when the binary carries no VCS metadata.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.