profile argument, which
targets one formae environment for a single call without changing which profile is
active. See
Targeting a specific environment.
Tools
Read-only
list_agent_plugins is the one to call before search_hub_plugins when authoring,
because it decides whether the hub catalogue is relevant at all. On formae Cloud the
set is closed: plugins ride the agent image, so one that is absent cannot be used and
authoring a new plugin will not make it available. It also reports the schema package
version to pin, which differs from the installed version for a -dev build.It lists the agent’s plugins, which is not what the local formae plugin list
reports — that one reads this machine’s package store.list_generators returns each generator’s label, stack, type, generation spec,
rotation interval, last committed rotation and bound resources. It never returns the
drawn value. An agent older than the feature reports none rather than failing.
Mutation
Policies
create_inline_policy above governs a single stack. A standalone policy is
declared once and attached to as many stacks as you like. See
Policies.
These four plan an edit and return a Pkl snippet with the line range to apply it at.
They modify nothing themselves: your assistant makes the edit, then simulates and
applies with apply_forma.
Two refusals are deliberate.
attach_standalone_policy rejects a stack that already
carries a policy of the same type, inline or standalone, because a stack holds only
one policy per type; the error names the conflict. delete_standalone_policy refuses
while the policy is still attached anywhere, and lists the stacks — detach and apply
first.
Deletion is also order-sensitive: edit the source to remove the declaration before
running the destroy the tool hands back. In that order, a reconcile landing between
the two steps sees no policy in any forma and does nothing. Reversed, it would
recreate the policy.
These require a project pinning the formae Pkl schema at 0.82.0 or later, which is
when policies arrived.
Local authoring context
These tools select and prepare local source without changing cloud resources. A profile chooses the formae installation; a codebase context chooses where the assistant maintains source for the current operation.set_drift_preference stores one of two choices for an installation: keep asking
about every out-of-band change, or automatically keep the ones that do not conflict
with your edits. Your assistant offers it once, after you have explicitly chosen to
keep a change — keeping one change is not consent to the policy, and no answer leaves
the setting alone. The preference is read back through get_codebase_context, never
authorizes a force or overrides a conflict, and you can change it whenever you like.
Conflicts, removals and ordinary apply confirmation are unaffected.
The assistant retains temporary authoring files through simulation, submission
and retry inspection, then removes them after the outcome is known or an unsent
preview is abandoned. An interrupted session can leave those files behind; they
are not registered as a maintained project.
Profiles
Requires formae >= 0.87.0. Manage named formae environments (endpoint + targets) from your assistant.formae Cloud
These cover signing in to formae Cloud and connecting a cloud account to it. A self-hosted agent needs none of them. Signing in takes two calls, because you do the browser step in between:login needs no profile and works on a machine where nothing is configured yet,
which is the case it exists for. Calling it with a session already open is harmless:
it reports that session and writes nothing. complete_login reports who signed in,
the profiles formae wrote for the installations your grants cover, and which profile
is now active; calling it without a preceding login is an error rather than a no-op.
Connecting a cloud account then differs by provider, because how much each one can
automate differs:
AWS has two routes. With credentials on the machine,
list_aws_profiles then
provision_cloud_role does the whole thing — it creates a real IAM role immediately,
plus the account-global OIDC identity provider if the account has none yet. Without
them, connect_cloud_account only computes a link; you apply the stack in your own
browser under your own session, and register_cloud_role records what it produced.
Azure splits the same way, between connect_azure_subscription and the
get_azure_trust_template / register_azure_trust pair. GCP has no console
equivalent, so connect_gcp_project is the only route.
Re-running a connect flow is safe: reporting that an account is already connected with
the same role or identity is a success, not a conflict. A listed connection is
registered, not verified — it does not confirm formae can use the role. If
list_cloud_connections reports that it could not determine the listing, that means
unknown, not “nothing is connected”.
register_azure_trust validates the shape of the coordinates only. It does not check
that the identity exists, trust the formae issuer, or grant anything.
Bug reports
Available on formae Cloud. Preparing and sending are separate tools so you see exactly what would leave your machine before any of it does.
The preview is immutable, and
submit_bug_report takes only the report_id and your
confirmation, so what is sent is exactly what you saw. Reports expire an hour after
preparation and are scoped to the MCP session that made them. Retrying delivery means
reusing the same report_id; if the configured recipient has changed, you get a new
preview to authorize instead. Submitting retries no infrastructure operation.
Local CLI diagnostics are included only where relevant — hosted agent logs are already
available to support, and inventories, whole forma files, transcripts and arbitrary log
files are never attached.
Self-hosted users report bugs through
GitHub issues or
Discord instead.