Documentation
¶
Overview ¶
Package cli provides the public entry point for embedding Forge's CLI as a subcommand in other cobra-based CLIs.
Copyright (c) 2025 Reliant Labs ¶
Copyright (c) 2025 Reliant Labs
Index ¶
- func ExitCode(err error) int
- func HandOffToPinned(ctx context.Context, args []string, stderr io.Writer) (handed bool, err error)
- func LoadSkill(projectRoot, skillPath string) ([]byte, error)
- func LoadSkillForAudience(projectRoot, skillPath, audience string) ([]byte, error)
- func NewRootCmd() *cobra.Command
- func RenderProjectMemory(projectRoot string) ([]byte, error)
- func RenderSkill(projectRoot, skillPath string, opts RenderSkillOptions) ([]byte, error)
- func SetVersion(version, buildDate, gitCommit string)
- type ListSkillsOptions
- type PinnedForge
- type RenderSkillOptions
- type Skill
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExitCode ¶ added in v1.0.0
ExitCode is the process status err should produce: the code the error carries (forge's agent verbs print the same number as their document's exit_code), else 1. A host that embeds forge's command tree must exit with it instead of a flat 1.
func HandOffToPinned ¶ added in v1.0.7
HandOffToPinned runs args — forge's own arguments, after the host's route (for `reliant forge generate -C x`, ["generate", "-C", "x"]) — under the forge the project in scope pins, when that is not this forge. A host that embeds forge calls it before executing its command tree, so a command the pinned forge has and this one lacks still reaches it.
It returns handed=false, err=nil when this forge is the one to run (no project, no pin — said on stderr when forge is embedded — the pin is this forge, or the user overrode the check), and an error, with nothing run, when the pinned forge is wanted and cannot be obtained. On success it replaces the process and does not return.
func LoadSkill ¶
LoadSkill returns the SKILL.md body for skillPath under projectRoot, honoring the same user > project > forge precedence as ListSkills. Returns an error if the skill is not found.
Version-skew advisory: when the skill is forge-shipped and the forge version serving it differs from the project's pinned forge_version (see Skill.VersionSkew), a one-line "Note: this guidance is from forge <X>; this project pins forge <Y>..." advisory is inserted after the YAML frontmatter so downstream readers see the skew inline.
func LoadSkillForAudience ¶
LoadSkillForAudience is like LoadSkill but filters the body for the given audience. Pass "general" to strip `<!-- @forge-only:start/end -->` blocks (e.g. when surfacing a skill outside a forge project). Pass "forge" or "" to keep the full body. Reliant and other harness shims should use this when a project lacks forge.yaml so emit:both skills surface without forge-specific tooling instructions.
func NewRootCmd ¶
NewRootCmd returns the fully assembled Forge root command. When embedded in another CLI (e.g. "reliant forge"), the internal Name() helper automatically adjusts user-facing command references.
func RenderProjectMemory ¶
RenderProjectMemory returns the rendered forge framework memory for a project (the bytes that would live in the project's top-level memory file — reliant.md / CLAUDE.md / etc.). Out-of-process consumers (notably the reliant CLI) use this to inject framework context into the LLM session without forge having to write a stale on-disk copy that drifts on framework upgrades.
projectRoot must be a directory containing forge.yaml. Returns an error when forge.yaml is missing or unreadable, or when the template cannot be rendered.
The template is read from the same embedded source that `forge project new` writes for non-reliant harnesses, so the in-memory and on-disk paths stay byte-identical.
func RenderSkill ¶ added in v0.1.45
func RenderSkill(projectRoot, skillPath string, opts RenderSkillOptions) ([]byte, error)
RenderSkill returns skillPath's content exactly as `<cli> skill load <skillPath>` prints it: the same user > project > forge resolution and version-skew advisory as LoadSkill, plus the command-name rewrite the CLI applies so every command in the skill is copy-pasteable under the mount that serves it. `skill load` itself calls the same renderer, so the two cannot drift.
Harnesses that inject a skill into an agent's context should use this rather than LoadSkill: the raw body says `forge generate`, which under a `reliant forge` mount names a command the agent may not have — or a different forge build than the one that generated its project.
A "forge/" prefix on skillPath is accepted, matching `skill load`.
func SetVersion ¶
func SetVersion(version, buildDate, gitCommit string)
SetVersion sets the version, build date, and git commit for the Forge CLI.
Types ¶
type ListSkillsOptions ¶
type ListSkillsOptions struct {
// IncludeMigrationSkills opts relevance=migration skills back into
// the listing (e.g. for an upgrade-assistant surface).
IncludeMigrationSkills bool
}
ListSkillsOptions tunes ListSkillsWithOptions. The zero value matches ListSkills' default behavior.
type PinnedForge ¶ added in v1.0.7
type PinnedForge = internalcli.PinnedForge
PinnedForge is the forge a project pins, resolved and ready to run: its executable, a Key naming exactly which forge it is (for caching what it prints), and Want, which forge the project asked for.
func ResolvePinnedForge ¶ added in v1.0.7
func ResolvePinnedForge(ctx context.Context, projectRoot, command string, log io.Writer) (PinnedForge, bool, error)
ResolvePinnedForge makes HandOffToPinned's decision for the forge command command ("skill load", "skill list") in projectRoot, and resolves the forge without running it, for a host that runs the project's forge itself. ok is false when this forge is the one to run command there; err, with the reason, when the project's forge is wanted and cannot be obtained — a host must then not substitute this forge's answer. log receives the one-time build notice.
type RenderSkillOptions ¶ added in v0.1.45
type RenderSkillOptions struct {
// Audience filters the body the same way as [LoadSkillForAudience]:
// "general" strips `@forge-only` blocks, "forge" or "" keeps the full
// body (which is what `skill load` prints).
Audience string
// CLIName is the command a reader types to invoke forge — "forge" for
// the standalone binary, "reliant forge" when forge is mounted inside
// reliant. Every bare `forge ` command reference in the body is
// rewritten to it. "" means the name this process reports for itself,
// the same one [RenderProjectMemory] renders, so a harness that injects
// both gets one consistent spelling.
CLIName string
}
RenderSkillOptions tunes RenderSkill. The zero value renders exactly what `forge skill load` prints from THIS process.
type Skill ¶
type Skill struct {
// Path is the skill identifier (e.g. "db", "frontend/state").
Path string
// Name is the human-readable name from the SKILL.md frontmatter.
Name string
// Description is the one-line summary from the SKILL.md frontmatter.
Description string
// Scope is where the skill was discovered: "forge", "project", or "user".
Scope string
// Emit declares which audience the skill targets — "forge" (framework
// skills, default when frontmatter omits the field), "general"
// (methodology that applies to any project), or "both" (mixed
// content, with framework-specific portions inside @forge-only
// blocks the renderer strips for general audiences). Consumers use
// this to decide whether to surface a skill outside a forge project.
Emit string
// Relevance classifies when the skill is worth surfacing: "" (always —
// the default) or "migration" (a one-time upgrade-transition playbook).
// ListSkills excludes relevance=migration skills; ListSkillsWithOptions
// can opt them back in. Consumers building their own retrieval layer
// should treat migration skills as transition-scoped, not steady-state.
Relevance string
// Version is the release that introduced the breaking change this
// migration skill covers, passed through verbatim from the `version:`
// frontmatter for consumers that want to do their own version gating.
// A project needs the migration when its pin is BELOW this version and
// it still exhibits the old shape.
//
// Forge itself gates listings on the relevance class only (binary
// versions are routinely dev builds / pseudo-versions, which are not
// meaningfully comparable); the authoritative project-aware version +
// detection gate is `forge project upgrade list`. Empty when undeclared
// and for non-migration skills.
Version string
// SkillForgeVersion is the forge version whose embedded templates the
// skill content comes from — i.e. the forge module linked into THIS
// process, not the project's pin. Empty for project/user-scope skills.
SkillForgeVersion string
// ProjectForgeVersion is the forge_version pinned in the project's
// forge.yaml ("" when projectRoot was empty, no pin is declared, or the
// file could not be read).
ProjectForgeVersion string
// VersionSkew is true when the serving forge version and the project's
// pin are both real release versions and differ. Harness consumers
// should surface skewed skills with caution: the guidance may describe
// a different forge version than the one that generated the project.
VersionSkew bool
}
Skill is the public metadata view of a forge skill, suitable for out-of-process consumers (e.g. reliant surfacing forge skills natively).
func ListSkills ¶
ListSkills returns every available forge skill for projectRoot — merging forge-shipped, project (.forge/skills under projectRoot), and user-global (~/.forge/skills) sources. On path collision, precedence is user > project > forge.
An empty projectRoot skips the project source. The result is sorted by Path. Returns an error only if the embedded forge-shipped skills cannot be enumerated; missing disk sources are silently skipped.
One-time migration skills (Relevance == "migration") are excluded from this default listing — they document specific forge version transitions and are noise for any project not mid-transition. Use ListSkillsWithOptions to opt them in; they always remain loadable by exact path via LoadSkill.
func ListSkillsWithOptions ¶
func ListSkillsWithOptions(projectRoot string, opts ListSkillsOptions) ([]Skill, error)
ListSkillsWithOptions is ListSkills with explicit listing options. Additive API — ListSkills' signature is stable for existing consumers.
Source Files