Actions File
actions.toml declares each thing a module does, keyed by the action's
ID: its command, its runtime arguments and the spec it reads, with the
shape it answers following from its resource and verb.
# actions.toml
schema = 1
[actions."env.approval.add"]
description = "Say yes, ahead of a run, to giving the environment file a secret it asks for"
role = "secondary"
docs = "/services/environments/approval#add-an-approval"
next = ["env.approval.list"]
[actions."env.approval.add".args]
secret = { type = "string", description = "The secret, by its name or its ID", required = true, x-link-cli = { position = 1 } }
spec = { type = "string", x-link-path = true, description = "The environment file (env.toml) that asks for it", required = true }Action IDs
An action is named whole as <namespace>.<resource>.<verb>. The
namespace is the module's ID from its module file, the
resource is a shape in its types file or the namespace's own
name, and the verb is its last part. The command comes from the ID,
lnk <namespace> <resource> <verb>, with the resource left out where it
is the namespace's own name. So env.env.create is lnk env create and
env.approval.add is lnk env approval add.
Programs
A namespace's program is lnk-<namespace>, and lnk <namespace> <resource> <verb> runs lnk-<namespace> <resource> <verb>, so a caller may run the
program directly. A program never sees its own namespace word, and a resource
named as the namespace collapses: web-tool.web-tool.serve is lnk-web-tool serve, typed as lnk web-tool serve.
Core's Namespace
Core is a namespace like any other, and its program is lnk itself. So
core.module.add is lnk module add. Core declares its own verbs under
[verbs], such as doctor, up, and upgrade, and its program's
flags under [program].
Verbs
A verb is one of Link's fixed verbs wherever its meaning applies, each
pair listed on the Catalog. A module declares
each other verb it uses under [verbs], with what it means, and every
declared verb is used by one of its actions. A declared verb meaning a
fixed one, such as new for create, is refused with the verb to say
instead, from format.toml's [verbs.banned].
# actions.toml
schema = 1
[verbs]
check = "Read an environment file and say what it sets up, making nothing"Fields
An action's table holds its help and how it's offered. Every key but
description may be left out:
description: its help, the first paragraph the short help and the rest shown with--help.args: its runtime arguments, by name.spec: the one spec kind it reads, by its name.output: the shape it answers, where its verb implies none or another (Outputs).stdin: the shape it reads on its standard input, when it reads one (Secrets on Standard Input).role:primary,secondary(the default) orplumbing, which says where help lists it. A plumbing action is hidden and offered on the command line alone.surfaces: where it's offered (Surfaces).nextandfail: the action IDs it suggests after success and after failure, which become Next's graph.checks: named hooks, functions of the crate'schecksmodule, run after the declared checks pass.docs: the guide section a person reads about it, as/<address>#<anchor>.default:truewhere its group, typed bare, runs it (Group Defaults).routeandtool: how a bridge offers it (Routes) and how a model calls it (Tools).diagnoses: on ashowaction, the kind of thing it diagnoses, such asboxorsecret. Given one by name, its--jsonis that thing's state, whichlnk issue createputs in a bug report.next-modules:trueon an action of core's leading into every module, aslnk updoes.
Reserved Fields
An action's resource, the argument naming what it acts on, and the module's
[roles], the action collections it comes with by name, are kept for access
control. The catalog reads them and checks their shape, and Catalog::on and
Catalog::role answer from them, but no command acts on them yet.
Runtime Arguments
Each entry of args is a runtime argument, about this one invocation,
such as a confirmation, an output switch, a resource selector or the
--spec file. Its name is its flag, and it never holds a dot. Its value
is a JSON Schema in the types file's subset, or a
shape's name, with description its help and required = true where it
must be given, as an OpenAPI parameter is written. An argument is a
scalar, a choice or a list of them, and an object written inline is
refused.
Command-Line Keys
Its x-link-cli table says how the command line takes it:
position: a positional argument, at this place from 1.short: its one-letter flag.rest: every argument after the others, a list of text passed on unparsed. Withlast, it's taken only after--, so a mistyped flag before it is refused rather than handed on.env: the variable read when the flag is absent, defined in a variables file. A switch reads none.shared: one of core's shared arguments.default-missing: the value the flag alone means, so its value is optional, as--sandboxalone is--sandbox own.conflictsandrequires: the arguments of the same action it can't be given with, or is only given with.hidden: kept out of help, for an argument Link passes and a person doesn't.
Defaults
A text, a number or a choice may declare a default, the value its
absence means, as the scheduler's driver declares default = "service". Its generated accessor then gives that value, its help shows
it, and every surface reads the same default. A required argument, a
switch or a list has none, and a default its own shape refuses is
refused when the module builds.
Positionals
Only a runtime argument is positional. The argument a person nearly
always gives, such as the cloud in lnk box create aws, is its command's positional. Its flag,
where it keeps one, is the optional strict form of the same argument. A
switch is never positional and never required, and a positional has no
short flag.
Shared Arguments
Core declares the arguments many modules take in link-actions'
shared.toml, each once with its help, and an action takes one by naming it,
as json = { x-link-cli = { shared = "json" } }. They are json, yes,
quiet, actions, relay, request, cloud, owner, account and
remote. A shared argument says nothing else, so its help is the same
everywhere. --relay falls back on LNK_RELAY, which a crate taking it
declares reading.
Shared Groups
A table of shared.toml with args is a group, taken whole by an
argument of its name. workplace = { x-link-cli = { shared = "workplace" } } gives --on, --cloud, --zone, --here and the place
positional after the action's own positionals, short for --cloud <cloud> or --here.
Argument Groups
Arguments several of a module's actions take together are declared
once, in [groups.<name>], and an action takes them all by an argument
naming the group. A group's arguments are optional flags on every
surface, and its generated arguments hold them as one Rust type, the
same in every action, so code handling them takes one type
(Argument Groups).
# actions.toml
schema = 1
[groups.flags]
description = "How the scheduler's runner is started"
args.driver = { enum = ["service", "cron", "address"], default = "service", description = "What wakes the runner" }
[actions."scheduler-tool.cron.install"]
description = "Have the machine's calendar start the runner"
[actions."scheduler-tool.cron.install".args]
flags = { group = "flags" }Arguments Every Action Takes
A runtime argument every action of the module takes, such as core's
--json, is declared once in a top-level [args] table.
Each action has it on every surface, and on the command line it goes
before or after the command's words. It is an optional flag, never
positional, and an action declaring the same name is refused.
# actions.toml
schema = 1
[args]
json = { x-link-cli = { shared = "json" } }Leaving an Argument Out
An action it doesn't fit writes it false in its own args, as
json = false for an action with no JSON answer. That action then has no
such argument on any surface, and the argument's accessor answers none
for it. A false naming no argument of [args] is refused.
Program Flags
[program] declares what the program does given no command, as lnk --version does, with an optional description and its flags in
[program.args]. Its flags are optional and never positional, and none
shares a name with [args]. A program declaring version gives its
own, and every other program has the version flag core's generator
gives it. A program declaring help renders its own help, as lnk --help does, while every command under it keeps clap's --help.
# actions.toml
schema = 1
[program.args]
version = { type = "boolean", description = "Print Link's installed version.", x-link-cli = { short = "V" } }Group Defaults
An action with default = true is what its group runs when typed with
no command after it, reading the action's flags there. With
core.module.list its group's default, lnk module runs lnk module list. A group has at most one default, and it's on the command
line. A plumbing action is a default only in a group of plumbing alone,
which Link runs bare and help hides. The default's flags are its own, so
given before another command of the group, as lnk <group> --<flag> <command>, they're refused, never dropped.
Specs and Outputs
spec binds the action to one spec kind by its name: its own, or
another module's as sandbox.sandbox, read through that module's
generated types. The kind's fields become field flags spelled as their
keys, nested fields by their dotted paths and top-level fields as
--spec.<field>. A field flag overrides the field it names in the file
--spec reads (Specs and Command
Lines).
Files Read as Written
An action that reads a spec file as written, such as one whose yes is
kept for that very file, binds no spec. It takes the file as an
argument marked x-link-path, as env.approval.add takes spec, so it
has no field flags.
Outputs
An action's output follows from its verb and its resource, the shape
its ID names, by format.toml's [verbs.fixed]:
- The resource:
show,create,add,set,get,connect,installandstart. - A list of the resource:
list. - The resource's ID, its
x-link-resourceproperty:delete,remove,disconnect,uninstallandstop.
Named Outputs
output names another shape where an action answers something else,
and every action with a module's own verb, or whose resource is no
shape, names one. An action whose --json is what it printed answers
core.report, link-format's blocks in order and its exit code. An
action relaying a tool's MCP result as it is answers core.mcp. A
person sees an output formatted by its verb, a list as a table and a
show as fields, and a shape's x-link-display names columns or labels
where that doesn't suit.
Secrets on Standard Input
An action that reads something on its standard input names that shape
in stdin, as output names what it answers. A value marked
x-link-sensitive is a secret, so an action whose output or stdin
shape reaches one prints or reads a secret. A recorder, such as a test
run's, keeps that stream out of what it saves by this declaration
alone:
# actions.toml
schema = 1
[actions."secret.secret.create"]
description = "Keep a secret"
role = "primary"
stdin = "value"# types.toml
schema = 1
[value]
type = "string"
description = "A secret's value, read from the first line of stdin"
x-link-sensitive = trueRoutes
An action a caller reaches through a bridge, the part of Link that
calls a module for a program it serves and enforces who may call and
how much it may answer, declares a route table. A route's answer is the action's
output, so no route names a type of its own.
# actions.toml
schema = 1
[actions."note.note.show"]
description = "Show a note"
[actions."note.note.show".route]
bridge = "command"
read-only = true
callers = ["owner", "program"]
limits = { bytes = 1048576, time_ms = 10000 }Route Keys
A route says who serves it, who may call it and what it may answer:
bridge: one offormat.toml's[route] kinds:command, a command run throughlnkand offered bylnk mcpand as a command tool,model, the model module's, the one[route]names as running the command itself, or the bridge the calling program has of its own.read-only: on acommandroute, that the command only reads.callers: who may call it, any ofowner,program,trigger, and the served program, which the bridge learns from authentication.limits: the most its answer may hold,bytes, and the longest it may take,time_ms, required unless its bridge runs the command itself.streams:truewhere its answer streams as it's made.carries: the protocol it relays in place of a typed answer, asmcp.commandandnames: that the served program's chat offers it as a command, and that command's other names, each a slash and a name.
Route Paths
A route's path and its chat command's name are its command's words with
the namespace, as /_link/box/list and box:list,
unless the route declares path, as a tool's "browser click". A route
with its own path may name its own docs section too. Two routes never
share a path, and two chat commands never share a name. An action only
its route offers, as a command its bridge alone runs, says surfaces = [].
Tools
An action offered on tool may name its MCP call in a tool table.
The module's [tools] table lists, once, what its program gives at
runtime: each fills value a description's {name} or an argument's
x-link-fill stands for, and each condition a call's when names.
# actions.toml
schema = 1
[tools]
fills = ["timeout", "programs"]
conditions = ["background"]
[actions."run-tool.run.command"]
description = "Runs a program, stopped after {timeout}"
surfaces = ["tool"]
output = "core.mcp"
[actions."run-tool.run.command".tool]
name = "command"
read-only = false
open-world = falseTool Keys
A tool table names the call and its annotations, MCP's hints a host
reads before it calls. Its action binds no spec, since a model's call
carries the action's runtime arguments alone:
name: the call's own name, once in the module.read-only: that it only reads, MCP'sreadOnlyHint.open-world: that it reaches beyond the machine, MCP'sopenWorldHint.destructive: that it may undo or overwrite what was there, MCP'sdestructiveHint, refused besideread-only = true.idempotent: that calling it again changes nothing more, MCP'sidempotentHint.when: the condition it's offered on, one of[tools]'sconditions, or always where left out.
Annotations
Each hint is given exactly when the table declares it, with its declared
value. One it leaves out is left out of the call's annotations, so MCP's
default holds: not read-only, destructive, not idempotent and open-world.
An argument marked x-link-summary is one the call's title shows, and a
boolean one marked x-link-asks makes the call ask the person first
(Tools).
Argument Names a Model Calls
A tool action's argument is declared with dashes, as every argument is
(start-coordinate), and its call names it with underscores
(start_coordinate), the shape models are trained on. The template, the
call's title and its asks name it so. A command line's flags keep their
dashes.
Checking a Call's Names
The program's check reads a
call's underscores as the declared dashes, refuses a call that gives the
dashes as an argument it doesn't have, and names each refused argument
as the model called it. Its handler reads the underscores too, and so
does a terminal action's --request, the call's own JSON. A declared name never holds an
underscore, so each name a model calls is one argument's. Only a
program's own calls are named so; an action offered as a tool without a
tool table keeps its declared names.
Fills
Braces in a tool action's description, or its arguments', name a fill
and mean nothing else. Every fill and condition [tools] declares is
used, and a fill is one kind, text in a description or an argument's
choices. The build renders the module's tool actions as a template with
every x-link-* keyword taken out, and the program fills it with
link_actions::tools::offer, which refuses a fill or condition the
declarations and the program disagree on.
Contracts
A contract is the protocol several modules answer alike, as every store
answers the store contract, so a caller calls whichever store it was
given the same way. A contract declares its protocol once, in its
contract crate's actions.toml, and each module implementing it lists
the actions it answers under [implements], by the contract's ID.
# actions.toml
schema = 1
[implements]
store = ["store.store.contract", "store.store.call", "store.store.serve"]Implemented Actions
Each listed action becomes the module's own under its namespace, with
the contract's arguments, spec and output, so store.store.serve
implemented by file-store is lnk-file-store serve. A resource the
contract names keeps its name. The catalog refuses an implementer whose
module.toml doesn't depend on the contract, a listed action the
contract doesn't declare, or one the module also declares itself. The
contract's shapes stay the contract's, generated once in its crate.
Given by Core
Core gives every module two kinds of command that actions.toml never
declares. uninstall reports and removes the parts a module keeps,
given only to a module whose module.toml declares [removal], and
core declares its own. spec show prints each spec kind the module
declares: the kind named as the namespace is lnk <namespace> spec show, and another kind has its own, lnk <namespace> <kind> spec show. No action's resource is spec, and no action's command is the
start of another's.
Core's Protocols
Two protocols sit outside a module's command space, each from its
module file. A module listing answers takes
the hidden root flag --link-answer <question>, and one running a guest
service has the hidden command guest-service. Every module's namespace
is dispatched to its program, lnk env ... to lnk-env, since core's
parser reads any namespace it doesn't declare as another module's.
Surfaces
An action is offered on the command line, the API, the app and as a
model's tool, each generated from this declaration. surfaces names a
narrower list of cli, api, app and tool, and a plumbing
action is offered on the command line alone. A list naming app
names api, which the app's page calls. An action whose list
leaves out cli, such as a tool a model calls, has no command and is
never a group's default, while its handler still answers its calls
(Actions Off the Command
Line).