The main func entry point contains the core runtime only. Optional capabilities use separate entry points and are covered in their own guides.
Commands and actions
| Signature | Parameters or shape | Description |
|---|---|---|
@Command(input) | string | readonly string[] | { path, alias?, aliases?, deprecated?, description? } | Register a named Command path; an alias replaces its final segment. |
@CommandMajor() | - | Register the major command with default, path, or flag Handlers. |
@CommandMissing() | - | Register a fallback Command when no named path matches. |
@Handler(input?) | '' | string | readonly string[] | { path?, flag?, alias?, aliases?, description? } | Register a default, path, or flag Handler; path excludes flag and aliases. |
@OptionCommand(params) | { name, alias?, aliases?, deprecated?, description?, overrideAll? } | Register a Module-scoped action option; the class has one default Handler. |
@Deprecated(message?) | message?: string | Deprecate a field option or flag Handler; Commands use deprecated. |
Command path and alias tokens cannot be empty, contain whitespace, or begin with -. An option alias must be one non-numeric character other than =.
Field options and validators
| Signature | Parameters | Description |
|---|---|---|
@Option() | - | Register a class as an injectable Module option Provider. |
@Flag(input?) | string | { name?, alias?, aliases?, description?, negatable? } | Declare a boolean option; negatable adds --no-<name>. |
@Value(input?) | string | { name?, alias?, aliases?, description? } | Declare a string or finite number inferred from metadata. |
createValueDecorator(transform) | (input: string) => Output | Create a decorator that synchronously transforms one string. |
@ArrayString(input?) | string | { name?, alias?, aliases?, description? } | Collect a repeated string option. |
@ArrayNumber(input?) | string | { name?, alias?, aliases?, description? } | Collect a repeated finite-number option. |
@Override() | - | Explicitly replace a same-named outer Module option field. |
@Required() | - | Require a value other than undefined; an initializer counts. |
@Enum(values) | Array<boolean | string | number> | Validate a scalar or every item in an array. |
@DependsOn(names) | string[] | When explicit, require the listed long option names as well. |
@Exclusive(names) | string[] | Reject an explicit combination with any listed long name. |
@ValueValidate(fn) | (value, options) => boolean | string | void | false or a string fails validation; no return value passes. |
Modules and dependency injection
| Signature | Parameters or shape | Description |
|---|---|---|
@Module(metadata) | { name?, commands?, imports?, options?, providers?, exports? } | Define the application or a feature Module; the root must be decorated. |
@Injectable() | - | Mark a class for class/useClass Providers; subclasses need their own. |
createToken<T>(description) | string | Create a typed, referentially compared InjectionToken<T>. |
@Inject(token) | Type | InjectionToken | Select an explicit token on a constructor or Handler parameter. |
Provider | Type | { provide, useClass } | { provide, useValue } | { provide, useFactory, inject? } | Define a Module Provider; factories may return asynchronously. |
Module.exports | ProviderToken[] | Export visible tokens; exports do not pass through intermediate Modules. |
imports accepts a Module class or a ModuleMetadata object returned by a dynamic Module. options accepts only classes decorated with @Option() or @OptionCommand(), never Provider objects.
Application and context
| Signature | Parameters or shape | Description |
|---|---|---|
createApp(module, options?) | { appName?: string, features?: ApplicationFeature[] } | Compile a one-shot process application; disk features require appName. |
app.bootstrap(options?) | { argv?, cwd?, env?, stdin?, stdout?, stderr?, signal? } | Start once, set process.exitCode, and return Promise<void>. |
createInvoker(module, options?) | { appName?: string }, imported from func/invoke | Create a reusable invoke(argv, options?) host without bootstrap. |
InvocationResult | { exitCode: number, result: unknown }, exported by func/invoke | The Handler result and exit code for one programmatic invocation. |
@Args() / Args | { raw, invokedPath, path, inputs, options } | Inject a frozen invocation snapshot into a Handler parameter only. |
@Ctx() | Context | Inject the complete runtime context for the current invocation. |
@Stdin() | Node.js Readable | Inject configured stdin, defaulting to process.stdin. |
@Stdout() | Node.js Writable | Inject configured stdout, defaulting to process.stdout. |
@Stderr() | Node.js Writable | Inject configured stderr, defaulting to process.stderr. |
Context | appName?, argv, command?, commands, options, io, cwd, env, signal, exitCode | Built-in DI context; raw argv is preserved and exit codes range 0–255. |
CommandInfo | { path, aliases, description?, deprecated?, fieldOptions? } | Deep-readonly metadata in Context.command and Context.commands. |
Args.path uses the canonical Command and Handler path. invokedPath preserves aliases typed by the user, inputs contains positional tokens left after path matching, and options uses public long names as keys.
Lifecycle and exceptions
| Signature or type | Shape | Description |
|---|---|---|
OnInit.onInit() | void | Promise<void> | Run after a managed instance has been prepared. |
OnDispose.onDispose() | void | Promise<void> | Release owned resources; failures enter onError after cleanup continues. |
OnError.onError(exception, context) | void | Promise<void> | Handle a Command or Module error; throw to continue outward. |
Exception | code, scope, details, message, cause | Stable structured subclass of Error. |
ErrorScope | SYSTEM | RUNTIME | Distinguish definition defects from invocation failures. |
formatExceptionCode() | (scope, code) => ExceptionCode | Build a complete error code with the F_*_ prefix. |
isException() | (value) => value is Exception | Test whether a value is a structured func exception. |
Optional capabilities
Optional capabilities are not re-exported by the main entry point. Their dedicated guides cover setup and customization:
| Entry | Guide |
|---|---|
func/help | Help |
func/testing | Testing |
func/testing/cli | Testing |
func/testing/fixtures | Testing |
func/testing/pty | Testing |
func/invoke | Programmatic invocation |
func/config | Configuration files |
func/log | Logging |
func/http | Networking |
func/http/testing | Networking |
func/net | Networking |
func/net/testing | Networking |
func/json-output | JSON output |
func/completion | Shell completion |
func/signals | Process signals |
funcgo and package configuration
| Signature | Shape | Description |
|---|---|---|
funcgo setup | --fix? | Inspect package.json; read-only by default, writes recommendations with --fix. |
funcgo dev | -f, --file <entry>; -- <args> | Run an entry with the local TypeScript runtime and forward trailing args. |
funcgo build | -f, --file <entry>; -o, --out <dir>; -e, --external <package>; -w, --watch; --watch-path <target> | Bundle the entry, create bin.js, and optionally rebuild for watched inputs. |
funcgo --help / --version | -h; -v | Print command help or the installed version. |
| package.json field | Description |
|---|---|
func.entry | TypeScript entry used by dev and build when --file is omitted. |
func.outDir | Build output directory when --out is omitted; defaults to dist. |
bin | Map the executable name users type to the generated bin.js. |