Shared Go CLI helpers and framework modules.
Module: github.com/gh-xj/agentcli-go
Repo: github.com/gh-xj/agentcli-go | Versioning: v0.x.y (pre-1.0)
| File | Exported Symbols |
|---|---|
| ------ | ----------------- |
log.go | InitLogger() — zerolog setup, respects -v/--verbose |
args.go | ParseArgs(args), RequireArg(args, name), GetArg(args, name), HasFlag(args, name) |
exec.go | RunCommand(name, args...), RunOsascript(script), Which(bin), CheckDependency(bin) |
fs.go | FileExists(path), EnsureDir(path), GetBaseName(path) |
core_context.go | AppContext{Meta, Values}, NewAppContext(ctx) |
lifecycle.go | Hook interface (Preflight, Postflight), RunLifecycle(app, hook, run) |
errors.go | CLIError, ResolveExitCode(err), ExitSuccess, ExitUsage |
scaffold.go | ScaffoldNew(baseDir, name, module), ScaffoldAddCommand(rootDir, name, desc, preset), Doctor(rootDir) DoctorReport |
cobrax/cobrax.go | Execute(RootSpec, args) int, NewRoot(RootSpec) *cobra.Command, CommandSpec, RootSpec |
configx/configx.go | Load(Options) map[string]any, DecodeT, NormalizeEnv(prefix, environ) |
agentcli new --name my-tool --module github.com/me/my-tool
# or programmatically:
agentcli.ScaffoldNew(".", "my-tool", "github.com/me/my-tool")
Generates: main.go, cmd/root.go, internal/app/, internal/config/, internal/io/, internal/tools/smokecheck/, pkg/version/, test/, Taskfile.yml, README.md
agentcli add command --name sync --preset file-sync
agentcli add command --name deploy --desc "run deploy checks"
Presets: file-sync, http-client, deploy-helper
agentcli doctor [--dir ./my-tool]
# returns DoctorReport JSON with findings
my-tool/
├── main.go # os.Exit(cmd.Execute(os.Args[1:]))
├── cmd/
│ ├── root.go # cobrax.Execute(RootSpec{...})
│ └── <command>.go # func <Name>Command() command
├── internal/
│ ├── app/{bootstrap,lifecycle,errors}.go
│ ├── config/{schema,load}.go
│ ├── io/output.go
│ └── tools/smokecheck/main.go
├── pkg/version/version.go
├── test/
│ ├── e2e/cli_test.go
│ └── smoke/version.schema.json
└── Taskfile.yml
// cmd/root.go
return cobrax.Execute(cobrax.RootSpec{
Use: "my-tool",
Short: "my-tool CLI",
Meta: agentcli.AppMeta{Name: "my-tool", Version: version.Version},
Commands: []cobrax.CommandSpec{
{Use: "sync", Short: "sync files", Run: SyncCommand().Run},
},
}, args)
Persistent flags auto-wired: --verbose/-v, --config, --json, --no-color
Values accessible via app.Values["json"], app.Values["config"], etc.
raw, err := configx.Load(configx.Options{
Defaults: map[string]any{"env": "default"},
FilePath: configPath, // optional JSON file
Env: configx.NormalizeEnv("MYTOOL_", os.Environ()),
Flags: map[string]string{"env": flagVal},
})
cfg, err := configx.Decode[config.Config](raw)
// Precedence: Defaults < File < Env < Flags
| Task | Purpose |
|---|---|
| ------ | --------- |
task ci | Canonical CI: preflight + lint + test + build + smoke + schema checks |
task verify | Local aggregate (wraps ci) |
task lint | go vet + golangci-lint |
task smoke | Deterministic smoke tests (subset of unit tests) |
task schema:check | Validate JSON contracts against schemas |
task docs:check | Ensure skill docs match CLI help signatures |
task fmt | Format all Go files |
package agentcli, no sub-packages (except cobrax, configx)log.Fatal allowed in RequireArg, CheckDependency (CLI-oriented helpers)共 1 个版本