CLI reference
Each section is what forculus <command> --help prints.
forculus
Section titled “forculus”Deploy apps, share them like a doc, and see who used them.
Usage: forculus [OPTIONS] <COMMAND>
Commands: login Sign in by approving this computer in your browser logout Sign out on this computer, or with --everywhere end every CLI session you have whoami Show who you're signed in as and your workspaces workspace Create workspaces, manage members and email domains, and check usage app Create, list, show and delete apps billing Show a workspace's plan and billing, or open its Billing tab sso Open a workspace's single sign-on settings in your browser. Owners set up a SAML or OpenID Connect provider there. A CLI session can read them with --status, but can't change who signs in to a workspace. An Enterprise feature, included on Business for early customers for a limited time. scim Open a workspace's SCIM settings in your browser. Owners make the token your identity provider uses there, shown once. An Enterprise feature, included on Business for early customers for a limited time. sessions List or revoke your CLI sessions connections List or disconnect the AI clients connected to apps as you, or to an app you manage init Start an app from a template, ready to deploy. With no template, list them. deploy Deploy a directory as a new version and make it live. Worker apps upload their modules. Container apps build the Dockerfile and push the image. import Bring a project over from Vercel, Netlify or Replit, or from any git repository, as a new app detect Show what `forculus deploy` would do with a directory, without building or deploying dockerfile Print the Dockerfile we'd build a container app with, or save it to the project versions List an app's versions scans Show what deploys' scans found: keys left in what was deployed, and packages with published vulnerabilities. With no version, the app's latest scans, refused deploys among them. rollback Make an earlier version live again scale Set how many containers a container app runs, each request going to one of them. The containers running keep running, and nothing rolls out unless the last deploy didn't finish. Containers past the new number stop within a few minutes. promote Make a preview live, as it is preview End a preview of an app: a version's, or a pull request's schedule Call a path on an app on a schedule share Give someone access to an app, or everyone at a domain, or a group. Takes effect within 60 seconds. unshare Remove someone's access to an app, or a domain's or a group's. It ends within 60 seconds, open connections too, unless the app is still shared with them another way, which is said. access List who has access to an app (people, domains and groups), or decide on the requests for access waiting on its owners group Manage a workspace's groups, to share apps with several people at once role Manage a workspace's custom roles: what a member may do, given to them or to a group policy Manage a workspace's publish policy: who may open its apps to the whole workspace, share them outside it, open public paths, make bypass tokens and agent credentials, and connect AI clients token Manage bypass tokens, which let scripts and services call an app agent Manage agents: named callers of a workspace's own, each reaching the apps you grant it with credentials of its own, and named as itself in the audit log secret Manage third-party credentials. We add them to an app's outbound requests. egress Choose which hosts an app may send requests to ai Share the workspace's AI provider keys with apps, each with a monthly budget postgres Connect a Postgres database you already have, like Neon, Supabase or RDS, and give it to apps. Its password stays with us. Apps query it through the platform. network Let apps reach systems inside your company's network, and see the fixed addresses they send from. Enterprise, where the platform has private networks switched on. env Manage an app's config values. Put credentials in `forculus secret set` instead. db Export an app's database or run a SQL statement on it domain Manage an app's custom domains, like app.example.com files List, download, upload or delete the files an app keeps kv Read, write or delete the keys an app keeps in key-value storage queue See how an app's queue is doing, or send it a message audit Show a workspace's audit log, newest first. For owners and admins, members whose custom role has audit.view, and an app's owners with --app. insights Show who opens a workspace's apps: people, opens and when each app was last opened, the apps nobody opened in 30, 60 or 90 days, and apps whose owners have all left. For owners and admins, members whose custom role has audit.view, and an app's owners with --app. webhook Send a workspace's events to a URL or a Slack channel. For owners and admins. audit-stream Stream a workspace's whole audit log to Splunk, Datadog, a URL or an S3 bucket. Owners set streams up, and owners and admins list them. An Enterprise feature, included on Business for early customers for a limited time. log-drain Send apps' logs to a URL, Datadog, Grafana Loki or an S3 bucket as they're written. A drain is for one app, added by whoever can share it, or for every app in a workspace, added by its owners. On Team, Business and Enterprise. watch Follow requests and changes to a workspace or app as they happen logs Show an app's output and exceptions, oldest first top Watch your apps, who has access and incoming requests in a live dashboard curl Send a request to an app through Forculus, as you or with a bypass token open Print an app's URL dev Run your app locally behind our sign-in edge, signed in as anyone you like mcp Serve this CLI to an agent over MCP, as the person signed in here uninstall Remove the CLI from this computer: its session, its files and the program. Your apps stay. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
-h, --help Print help (see a summary with '-h')
-V, --version Print version
Getting started: forculus login forculus workspace create acme forculus deploy acme/hello ./my-app --create forculus share acme/hello someone@example.com
Apps are always named <workspace>/<app>. Run `forculus <command> --help` formore on any command.
Environment: The CLI trusts its environment the way git, gh and the AWS CLI do. FORCULUS_API, FORCULUS_APPS_URL, FORCULUS_CONFIG_DIR, XDG_CONFIG_HOME, HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY, FORCULUS_CA_FILE, SSL_CERT_FILE, FORCULUS_IMPORT_VERCEL_API and FORCULUS_IMPORT_NETLIFY_API control where it connects, what it trusts and where it keeps your session. Only set them to values you chose, and that includes anything a tool like direnv loads from a project's .envrc.
The CLI never reads a .env file, unless you name one with `forculus import --env-file`. It never sends a token to another machine over plain http, and never sends localhost or loopback traffic through a proxy. If you sign in to any API other than https://api.forculuslabs.tech, `forculus login` tells you which one.
Yun, our cloud, turns up at a few moments when you're at a terminal. FORCULUS_NO_MASCOT=1 turns Yun off. Yun never shows with --json, NO_COLOR or CI set, or when the output goes to a pipe or a file.forculus login
Section titled “forculus login”Sign in by approving this computer in your browser
Usage: forculus login [OPTIONS]
Options: --api <API> The API to sign in to. Defaults to https://api.forculuslabs.tech, or the local one with --dev. [env: FORCULUS_API] --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --dev <EMAIL> Local only: sign in as this email, using the code from the local inbox --inbox <URL> Local only: the local inbox. Defaults to http://inbox.forculus.localhost on the API's port. --no-browser Print the approval link instead of opening a browser -h, --help Print helpforculus logout
Section titled “forculus logout”Sign out on this computer, or with --everywhere end every CLI session you have
Usage: forculus logout [OPTIONS]
Options: --everywhere End every CLI session you have, this one too, and disconnect every AI client you connected. Your browser sessions end from the dashboard's Sessions page. Bypass tokens and agent credentials you made keep working: add --tokens to revoke them too. --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --tokens With --everywhere: also revoke every bypass token and agent credential you made, in every workspace. For a lost laptop, or someone leaving. -h, --help Print helpforculus whoami
Section titled “forculus whoami”Show who you're signed in as and your workspaces
Usage: forculus whoami [OPTIONS]
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus workspace
Section titled “forculus workspace”Create workspaces, manage members and email domains, and check usage
Usage: forculus workspace [OPTIONS] <COMMAND>
Commands: create Create a workspace for your apps. You'll be its owner. list List your workspaces, with your role and the plan for each show Show a workspace: your role, its plan and who can join members List a workspace's members and their roles add Add a member or change their role remove Remove a member domains Show the email domains members and sharing are limited to, limit them to these, or allow any with --clear scan-policy Show or set what a deploy's scan does with what it finds: warn, the default, or block. Set for secrets and for critical vulnerabilities apart. For owners and admins. Blocking can be turned on here, but turning it off is done in the dashboard. deleted List the deleted workspaces you own that can still be restored, and until when restore Restore a deleted workspace you own, as it was, on the Free plan. Its tokens stay revoked. delete Delete a workspace, or with --for-good one already deleted. It opens the dashboard page for it in your browser, where an owner signed in in the last 15 minutes types the workspace's short name to confirm. Where deleted workspaces are kept, it's kept for 30 days, and `forculus workspace restore` brings it back until then. Nothing is kept while an owner of it or of one of its apps has yet to accept our terms, which are what promise a deletion that waits. The page says which applies. A CLI session can deploy, but it can't delete a workspace. export Download everything in a workspace as JSON: its members, apps, grants and the audit log your plan keeps. It opens the workspace's settings in your browser, where an owner signed in in the last 15 minutes chooses Export. A CLI session can deploy, but it can't carry the workspace off. usage Show a workspace's usage this billing month and the cost so far. For owners and admins, and members whose custom role has billing.view. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus workspace create
Section titled “forculus workspace create”Create a workspace for your apps. You'll be its owner.
Usage: forculus workspace create [OPTIONS] <SLUG>
Arguments: <SLUG> Its short name, which starts every app name. Use lowercase letters, digits and single dashes.
Options: --json Print machine-readable JSON instead of text --name <NAME> A display name. Defaults to the slug. --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --region <REGION> Where its apps' databases, files, containers and archived audit log are kept: us, or eu where the platform offers it. The US unless you say. It can't change later, and apps in an EU workspace need Enterprise. [possible values: us, eu] -h, --help Print helpforculus workspace list
Section titled “forculus workspace list”List your workspaces, with your role and the plan for each
Usage: forculus workspace list [OPTIONS]
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus workspace show
Section titled “forculus workspace show”Show a workspace: your role, its plan and who can join
Usage: forculus workspace show [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus workspace members
Section titled “forculus workspace members”List a workspace's members and their roles
Usage: forculus workspace members [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus workspace add
Section titled “forculus workspace add”Add a member or change their role
Usage: forculus workspace add [OPTIONS] <WORKSPACE> <EMAIL>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
<EMAIL> Their email address
Options: --json Print machine-readable JSON instead of text
--role <ROLE> What they can do in the workspace
Possible values: - member: Uses apps shared with them or with the whole workspace - admin: Can also manage every app, the members and the audit log - owner: Can also add and remove owners
[default: member]
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
--custom-role <NAME> A custom role to give a member, by name. See `forculus role`.
-h, --help Print help (see a summary with '-h')forculus workspace remove
Section titled “forculus workspace remove”Remove a member
Usage: forculus workspace remove [OPTIONS] <WORKSPACE> <EMAIL>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <EMAIL> Their email address
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus workspace domains
Section titled “forculus workspace domains”Show the email domains members and sharing are limited to, limit them to these,or allow any with --clear
Usage: forculus workspace domains [OPTIONS] <WORKSPACE> [DOMAINS]
Arguments: <WORKSPACE> The workspace slug. For example, acme. [DOMAINS] The domains, separated by commas. For example, example.com,example.org. Leave out to show the ones set now.
Options: --clear Allow any email domain again --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --yes Save a list that leaves out the domain of your own address, which locks you out of every app in the workspace within a minute -h, --help Print helpforculus workspace scan-policy
Section titled “forculus workspace scan-policy”Show or set what a deploy's scan does with what it finds: warn, the default, orblock. Set for secrets and for critical vulnerabilities apart. For owners andadmins. Blocking can be turned on here, but turning it off is done in thedashboard.
Usage: forculus workspace scan-policy [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --secrets <SECRETS> What a deploy with a possible secret in it does [possible values: warn, block] --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --vulnerabilities <VULNERABILITIES> What a deploy with a package that has a critical vulnerability does [possible values: warn, block] -h, --help Print helpforculus workspace deleted
Section titled “forculus workspace deleted”List the deleted workspaces you own that can still be restored, and until when
Usage: forculus workspace deleted [OPTIONS]
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus workspace restore
Section titled “forculus workspace restore”Restore a deleted workspace you own, as it was, on the Free plan. Its tokensstay revoked.
Usage: forculus workspace restore [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus workspace delete
Section titled “forculus workspace delete”Delete a workspace, or with --for-good one already deleted. It opens thedashboard page for it in your browser, where an owner signed in in the last 15minutes types the workspace's short name to confirm. Where deleted workspacesare kept, it's kept for 30 days, and `forculus workspace restore` brings it backuntil then. Nothing is kept while an owner of it or of one of its apps has yetto accept our terms, which are what promise a deletion that waits. The page sayswhich applies. A CLI session can deploy, but it can't delete a workspace.
Usage: forculus workspace delete [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --for-good Delete one you deleted for good now, rather than when the 30 days it's kept are up --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --no-browser Print the address instead of opening a browser -h, --help Print helpforculus workspace export
Section titled “forculus workspace export”Download everything in a workspace as JSON: its members, apps, grants and theaudit log your plan keeps. It opens the workspace's settings in your browser,where an owner signed in in the last 15 minutes chooses Export. A CLI sessioncan deploy, but it can't carry the workspace off.
Usage: forculus workspace export [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --no-browser Print the address instead of opening a browser --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus workspace usage
Section titled “forculus workspace usage”Show a workspace's usage this billing month and the cost so far. For owners andadmins, and members whose custom role has billing.view.
Lists each meter against what your plan includes, with the cost before tax. Thenyour usage limit, any credits and a table of apps. On Free, shows the monthagainst Free's limits.
Usage: forculus workspace usage [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --app <APP> Only show this app in the table, by slug or <workspace>/<app>
--json Print machine-readable JSON instead of text
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
--previous Show last month instead
-h, --help Print help (see a summary with '-h')forculus app
Section titled “forculus app”Create, list, show and delete apps
Usage: forculus app [OPTIONS] <COMMAND>
Commands: create Create an empty app. `forculus deploy --create` does this for you. list List the apps you can see in a workspace. Owners and admins also see, under each, who can open it, what it sends requests to, who made it and when it was last opened. With --shared, list apps shared with you from workspaces you're not in. show Show an app: its URL, driver, live version and your role visibility Set who can reach an app. private: only people you share it with. workspace: everyone in the workspace, as a viewer mcp Let AI clients such as Claude and Cursor connect to an app that is an MCP server, or stop them. Each signs in as someone the app is shared with, who approves it in a browser. delete Delete an app. It goes offline and its tokens are revoked at once. Where deleted apps are kept, its data and settings are kept for 30 days, and `forculus app restore` brings it back until then, unless you add --for-good. Nothing is kept while an owner of the workspace or of the app has yet to accept our terms, whoever deletes it. Without --yes it says which applies. deleted List a workspace's deleted apps that you can restore, and until when restore Restore a deleted app as it was: its versions, data, settings and who it's shared with. Its tokens stay revoked. public-paths List paths anyone can reach without signing in, and how each is verified. Change them in the dashboard. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus app create
Section titled “forculus app create”Create an empty app. `forculus deploy --create` does this for you.
Usage: forculus app create [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text
--name <NAME> A display name. Defaults to the app's slug.
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
--driver <DRIVER> What runs it. You can't change this later.
Possible values: - workers: Worker apps and static sites: what `--kind worker` and `--kind static` deploy - containers: Container apps: what `--kind container` deploys
[default: workers]
--visibility <VISIBILITY> Who can reach it
Possible values: - private: Only people you share it with - workspace: Everyone in the workspace, as a viewer
[default: private]
-h, --help Print help (see a summary with '-h')forculus app list
Section titled “forculus app list”List the apps you can see in a workspace. Owners and admins also see, undereach, who can open it, what it sends requests to, who made it and when it waslast opened. With --shared, list apps shared with you from workspaces you're notin.
Usage: forculus app list [OPTIONS] [WORKSPACE]
Arguments: [WORKSPACE] The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --shared List apps shared with you from workspaces you're not in --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus app show
Section titled “forculus app show”Show an app: its URL, driver, live version and your role
Usage: forculus app show [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus app visibility
Section titled “forculus app visibility”Set who can reach an app. private: only people you share it with. workspace:everyone in the workspace, as a viewer
Usage: forculus app visibility [OPTIONS] <WORKSPACE/APP> <VISIBILITY>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
<VISIBILITY> Who can reach it
Possible values: - private: Only people you share it with - workspace: Everyone in the workspace, as a viewer
Options: --json Print machine-readable JSON instead of text
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
-h, --help Print help (see a summary with '-h')forculus app mcp
Section titled “forculus app mcp”Let AI clients such as Claude and Cursor connect to an app that is an MCPserver, or stop them. Each signs in as someone the app is shared with, whoapproves it in a browser.
Usage: forculus app mcp [OPTIONS] <WORKSPACE/APP> <STATE>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <STATE> Whether AI clients can connect [possible values: on, off]
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus app delete
Section titled “forculus app delete”Delete an app. It goes offline and its tokens are revoked at once. Where deletedapps are kept, its data and settings are kept for 30 days, and `forculus apprestore` brings it back until then, unless you add --for-good. Nothing is keptwhile an owner of the workspace or of the app has yet to accept our terms,whoever deletes it. Without --yes it says which applies.
Usage: forculus app delete [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --yes Confirm the delete. This takes the app offline and revokes its tokens. --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --for-good Delete its data and versions for good now, rather than keeping them for 30 days. Works on an app already in Recently deleted too. --kept You were told it's kept for 30 days. If deleting it would be final by now, because an owner who has yet to accept our terms was added since, nothing is deleted. -h, --help Print helpforculus app deleted
Section titled “forculus app deleted”List a workspace's deleted apps that you can restore, and until when
Usage: forculus app deleted [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus app restore
Section titled “forculus app restore”Restore a deleted app as it was: its versions, data, settings and who it'sshared with. Its tokens stay revoked.
Usage: forculus app restore [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus app public-paths
Section titled “forculus app public-paths”List paths anyone can reach without signing in, and how each is verified. Changethem in the dashboard.
Usage: forculus app public-paths [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus billing
Section titled “forculus billing”Show a workspace's plan and billing, or open its Billing tab
Usage: forculus billing [OPTIONS] <COMMAND>
Commands: show Show a workspace's plan and billing: what it costs, when it renews and anything waiting, or an Enterprise contract's terms and invoices. For owners and admins, and members whose custom role has billing.view. `forculus workspace usage` has each meter and each app's share. open Open the workspace's Billing tab in your browser. On Team and Business, owners change the plan, the card and the usage limit there: paying stays in the browser. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus billing show
Section titled “forculus billing show”Show a workspace's plan and billing: what it costs, when it renews and anythingwaiting, or an Enterprise contract's terms and invoices. For owners and admins,and members whose custom role has billing.view. `forculus workspace usage` haseach meter and each app's share.
Usage: forculus billing show [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus billing open
Section titled “forculus billing open”Open the workspace's Billing tab in your browser. On Team and Business, ownerschange the plan, the card and the usage limit there: paying stays in thebrowser.
Usage: forculus billing open [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --no-browser Print the address instead of opening a browser --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus sso
Section titled “forculus sso”Open a workspace's single sign-on settings in your browser. Owners set up a SAMLor OpenID Connect provider there. A CLI session can read them with --status, butcan't change who signs in to a workspace. An Enterprise feature, included onBusiness for early customers for a limited time.
Usage: forculus sso [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --no-browser Print the address instead of opening a browser --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --status Show the provider, who has to use it and the workspace's domains instead. Owners only. -h, --help Print helpforculus scim
Section titled “forculus scim”Open a workspace's SCIM settings in your browser. Owners make the token youridentity provider uses there, shown once. An Enterprise feature, included onBusiness for early customers for a limited time.
Usage: forculus scim [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --no-browser Print the address instead of opening a browser --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --status Show whether its identity provider has a working token instead, never the token. Owners only. -h, --help Print helpforculus sessions
Section titled “forculus sessions”List or revoke your CLI sessions
Usage: forculus sessions [OPTIONS] <COMMAND>
Commands: list List your CLI sessions, newest first, with the one you're using marked. Your browser sessions are on the dashboard's Sessions page. revoke Revoke one of your CLI sessions. It stops working on its next request. To end them all, this one too, run `forculus logout --everywhere`. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus sessions list
Section titled “forculus sessions list”List your CLI sessions, newest first, with the one you're using marked. Yourbrowser sessions are on the dashboard's Sessions page.
Usage: forculus sessions list [OPTIONS]
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus sessions revoke
Section titled “forculus sessions revoke”Revoke one of your CLI sessions. It stops working on its next request. To endthem all, this one too, run `forculus logout --everywhere`.
Usage: forculus sessions revoke [OPTIONS] <ID>
Arguments: <ID> The session's id, from `forculus sessions list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus connections
Section titled “forculus connections”List or disconnect the AI clients connected to apps as you, or to an app youmanage
Usage: forculus connections [OPTIONS] <COMMAND>
Commands: list List the AI clients you connected to apps, or with --app every client connected to an app, for its owners and the workspace's owners and admins disconnect Disconnect an AI client. It's refused from its next request. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus connections list
Section titled “forculus connections list”List the AI clients you connected to apps, or with --app every client connectedto an app, for its owners and the workspace's owners and admins
Usage: forculus connections list [OPTIONS]
Options: --app <WORKSPACE/APP> List the clients connected to this app instead, as <workspace>/<app> --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus connections disconnect
Section titled “forculus connections disconnect”Disconnect an AI client. It's refused from its next request.
Usage: forculus connections disconnect [OPTIONS] [ID]
Arguments: [ID] The connection's id, from `forculus connections list`
Options: --app <WORKSPACE/APP> End a connection to this app, as one of its owners or the workspace's owners and admins --json Print machine-readable JSON instead of text --all Disconnect every AI client you connected --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus init
Section titled “forculus init”Start an app from a template, ready to deploy. With no template, list them.
Writes the template's files into a new directory, or one without them. A filethat's already there is never replaced: if any is, nothing is written.
Usage: forculus init [OPTIONS] [TEMPLATE] [DIR]
Arguments: [TEMPLATE] The template
Possible values: - static-site: A plain HTML and CSS page, served as files. Nothing to install or build. - worker: A JavaScript Worker that greets whoever signed in and shows their role. - internal-tool: A Worker with a database: a list your team shares and adds to. - express: A Node server with Express, run as a container. Needs a paid plan. - fastapi: A Python app with FastAPI, run as a container. Needs a paid plan.
[DIR] Where to put it. Defaults to ./<template>.
Options: --json Print machine-readable JSON instead of text
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
-h, --help Print help (see a summary with '-h')forculus deploy
Section titled “forculus deploy”Deploy a directory as a new version and make it live. Worker apps upload theirmodules. Container apps build the Dockerfile and push the image.
In GitHub Actions, the Forculus-Labs/forculus/actions/deploy action handsover a credential the run's OIDC token was traded for, in the fileFORCULUS_DEPLOY_TOKEN_FILE names (read, then deleted) or inFORCULUS_DEPLOY_TOKEN. The deploy uses it in place of a login, and sends it tothe API FORCULUS_API names, or to https://api.forculuslabs.tech. It deploys theone app it was made for, which has to exist already.
Usage: forculus deploy [OPTIONS] <WORKSPACE/APP> [DIR]
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
[DIR] The directory to deploy
[default: .]
Options: --json Print machine-readable JSON instead of text
--kind <KIND> Deploy it as this kind if the directory doesn't make it clear
Possible values: - static: Static files, served as they are - worker: JavaScript on Workers - container: An image that runs as a container
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
--create Create the app if it doesn't exist yet
--visibility <VISIBILITY> Who can reach the new app. Needs --create.
Possible values: - private: Only people you share it with - workspace: Everyone in the workspace, as a viewer
[default: private]
--dry-run Show what would be deployed, then stop
--no-build Skip the project's build and deploy what's already built
--main <MAIN> Worker apps: the entry module. Naming one makes this a Worker, as worker.main in forculus.json does. Without it we look for index.js, src/index.js, dist/index.js, worker.js and src/worker.js, and their .mjs versions.
--compatibility-date <COMPATIBILITY_DATE> Worker apps: the compatibility date
--port <PORT> Container apps: the port the image listens on. Defaults to "port" in forculus.json, then the live version's port, then 8080.
--instance-type <INSTANCE_TYPE> Container apps: the instance size. Defaults to "instance_type" in forculus.json, then the live version's size, then basic. `forculus workspace show` lists the sizes your plan runs.
[possible values: lite, basic, standard-1, standard-2, standard-3, standard-4]
--instances <INSTANCES> Container apps: how many containers to run, each request going to one of them. Defaults to "instances" in forculus.json, then the number the app runs now, which starts at 1. `forculus workspace show` gives how many your plan runs.
--preview Put it up at a preview address of its own and leave the live version as it is. Worker apps and static sites only. Only people the app is shared with can open it, for 7 days or until the app's next preview. `forculus promote` puts it live.
-h, --help Print help (see a summary with '-h')forculus import
Section titled “forculus import”Bring a project over from Vercel, Netlify or Replit, or from any git repository,as a new app.
Reads the project's settings and production variables from the host's API with atoken you paste, used for this import only and never saved: VERCEL_TOKEN orNETLIFY_AUTH_TOKEN if set. Clones the code with your git, writes aforculus.json, makes the app, sets plain variables as environment variables andAPI keys as secrets, deploys it and adds its scheduled calls. It shows all ofthat and asks first. What can't come along is said, with what to do instead.
Usage: forculus import [OPTIONS] <FROM> <WORKSPACE/APP> [DIR]
Arguments: <FROM> Where the project is now: vercel:<project>, netlify:<site>, replit (the Repl's files, in DIR), a git repository's address, or a directory with the code, such as a Lovable, Bolt or v0 export
<WORKSPACE/APP> The app to make, as <workspace>/<app>. It mustn't exist yet.
[DIR] Where the code is, or where to clone it. Defaults to a new directory named after the project. For replit, the Repl's files, which defaults to the current directory.
Options: --json Print machine-readable JSON instead of text
--team <TEAM> The Vercel team the project belongs to, by its id or slug
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
--env-file <FILE> A .env file with values to use, such as Replit's Secrets (Edit as .env), or the values a host keeps write-only. It's read here and nowhere else.
--kind <KIND> Deploy it as this kind if the code doesn't make it clear
Possible values: - static: Static files, served as they are - worker: JavaScript on Workers - container: An image that runs as a container
--dry-run Show what would happen, then stop. Nothing is made, written or deployed.
--no-deploy Make the app and set its variables and secrets, but don't deploy it
-y, --yes Don't ask before going ahead. Needed when there's no terminal to ask at.
-h, --help Print help (see a summary with '-h')forculus detect
Section titled “forculus detect”Show what `forculus deploy` would do with a directory, without building ordeploying
Usage: forculus detect [OPTIONS] [DIR]
Arguments: [DIR] The directory to look at
[default: .]
Options: --json Print machine-readable JSON instead of text
--kind <KIND> Treat it as this kind, like `forculus deploy --kind`
Possible values: - static: Static files, served as they are - worker: JavaScript on Workers - container: An image that runs as a container
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
-h, --help Print help (see a summary with '-h')forculus dockerfile
Section titled “forculus dockerfile”Print the Dockerfile we'd build a container app with, or save it to the project
Usage: forculus dockerfile [OPTIONS] [DIR]
Arguments: [DIR] The app's directory
[default: .]
Options: --json Print machine-readable JSON instead of text
--kind <KIND> Treat it as this kind, like `forculus deploy --kind`
Possible values: - static: Static files, served as they are - worker: JavaScript on Workers - container: An image that runs as a container
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
--write Save it as ./Dockerfile. Deploys build from your copy after that.
-h, --help Print help (see a summary with '-h')forculus versions
Section titled “forculus versions”List an app's versions
Usage: forculus versions [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus scans
Section titled “forculus scans”Show what deploys' scans found: keys left in what was deployed, and packageswith published vulnerabilities. With no version, the app's latest scans, refuseddeploys among them.
Usage: forculus scans [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --version <VERSION> One version's whole scan --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --id <ID> One scan by its id, as a refused deploy names it -h, --help Print helpforculus rollback
Section titled “forculus rollback”Make an earlier version live again
Usage: forculus rollback [OPTIONS] <WORKSPACE/APP> <VERSION>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <VERSION> The version number, from `forculus versions`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus scale
Section titled “forculus scale”Set how many containers a container app runs, each request going to one of them.The containers running keep running, and nothing rolls out unless the lastdeploy didn't finish. Containers past the new number stop within a few minutes.
Usage: forculus scale [OPTIONS] <WORKSPACE/APP> <INSTANCES>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <INSTANCES> How many containers, from 1. `forculus workspace show` gives how many your plan runs.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus promote
Section titled “forculus promote”Make a preview live, as it is
Usage: forculus promote [OPTIONS] <WORKSPACE/APP> <VERSION>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <VERSION> The preview's version number, from `forculus versions`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus preview
Section titled “forculus preview”End a preview of an app: a version's, or a pull request's
Usage: forculus preview [OPTIONS] <COMMAND>
Commands: end End a preview: one version's, from `forculus versions`, or the one a pull request's GitHub run put up. Its address stops answering at once. The live version stays as it is. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus preview end
Section titled “forculus preview end”End a preview: one version's, from `forculus versions`, or the one a pullrequest's GitHub run put up. Its address stops answering at once. The liveversion stays as it is.
The deploy action runs it with --pull-request when the pull request closes, withthe credential its run traded for. Anyone who can deploy the app can run it too.
Usage: forculus preview end [OPTIONS] <WORKSPACE/APP> [VERSION]
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
[VERSION] The version whose preview to end
Options: --json Print machine-readable JSON instead of text
--pull-request <PULL_REQUEST> End this pull request's preview instead, by its number
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
-h, --help Print help (see a summary with '-h')forculus schedule
Section titled “forculus schedule”Call a path on an app on a schedule
Usage: forculus schedule [OPTIONS] <COMMAND>
Commands: add Call a path on the app on a schedule. Each run is a request to the app, signed as the scheduler, and counts toward your plan like any other. list List an app's schedules, with when each runs next and how its last run went remove Remove a schedule. It doesn't run again. run Run a schedule now. It runs within a minute, the way it always does. on Turn a schedule on. It runs next at the first time its expression names from now. off Turn a schedule off. It's kept, and doesn't run until it's turned on again. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus schedule add
Section titled “forculus schedule add”Call a path on the app on a schedule. Each run is a request to the app, signedas the scheduler, and counts toward your plan like any other.
Usage: forculus schedule add [OPTIONS] <WORKSPACE/APP> <CRON> <PATH>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <CRON> When, as five cron fields in UTC: minute, hour, day of the month, month, day of the week. For example, "0 6 * * 1-5" is 06:00 UTC on weekdays. <PATH> The path to call. For example, /jobs/nightly.
Options: --json Print machine-readable JSON instead of text --method <METHOD> The method to call it with [default: post] [possible values: post, get] --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus schedule list
Section titled “forculus schedule list”List an app's schedules, with when each runs next and how its last run went
Usage: forculus schedule list [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus schedule remove
Section titled “forculus schedule remove”Remove a schedule. It doesn't run again.
Usage: forculus schedule remove [OPTIONS] <WORKSPACE/APP> <ID>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <ID> The schedule's id, from `forculus schedule list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus schedule run
Section titled “forculus schedule run”Run a schedule now. It runs within a minute, the way it always does.
Usage: forculus schedule run [OPTIONS] <WORKSPACE/APP> <ID>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <ID> The schedule's id, from `forculus schedule list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus schedule on
Section titled “forculus schedule on”Turn a schedule on. It runs next at the first time its expression names fromnow.
Usage: forculus schedule on [OPTIONS] <WORKSPACE/APP> <ID>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <ID> The schedule's id, from `forculus schedule list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus schedule off
Section titled “forculus schedule off”Turn a schedule off. It's kept, and doesn't run until it's turned on again.
Usage: forculus schedule off [OPTIONS] <WORKSPACE/APP> <ID>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <ID> The schedule's id, from `forculus schedule list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus share
Section titled “forculus share”Give someone access to an app, or everyone at a domain, or a group. Takes effectwithin 60 seconds.
Usage: forculus share <WORKSPACE/APP> <EMAIL|@DOMAIN> [--role <ROLE>] forculus share <WORKSPACE/APP> --group <NAME>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
[EMAIL|@DOMAIN] Their email address, or @ and a domain to let in everyone whose address is exactly at it, like @acme.com. To let everyone in the workspace in, run `forculus app visibility <workspace>/<app> workspace`.
Options: --group <NAME> Share it with one of the workspace's groups instead. See `forculus group`.
--json Print machine-readable JSON instead of text
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
--role <ROLE> What they can do. A domain or a group can only be a viewer.
Possible values: - viewer: Uses the app - editor: Can also deploy it and manage its config, secrets and tokens - owner: Can also share and delete it
[default: viewer]
-h, --help Print help (see a summary with '-h')forculus unshare
Section titled “forculus unshare”Remove someone's access to an app, or a domain's or a group's. It ends within 60seconds, open connections too, unless the app is still shared with them anotherway, which is said.
Usage: forculus unshare <WORKSPACE/APP> <EMAIL|@DOMAIN> forculus unshare <WORKSPACE/APP> --group <NAME>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. [EMAIL|@DOMAIN] Their email address, or @ and the domain, like @acme.com
Options: --group <NAME> Unshare it with this group instead --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus access
Section titled “forculus access”List who has access to an app (people, domains and groups), or decide on therequests for access waiting on its owners
Usage: forculus access [OPTIONS] <WORKSPACE/APP> forculus access <COMMAND>
Commands: requests List the open requests for access to an app, with what each person wrote approve Approve a request: share the app with them as a viewer and email them its link deny Turn a request down. They aren't told. help Print this message or the help of the given subcommand(s)
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus access requests
Section titled “forculus access requests”List the open requests for access to an app, with what each person wrote
Usage: forculus access requests [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus access approve
Section titled “forculus access approve”Approve a request: share the app with them as a viewer and email them its link
Usage: forculus access approve [OPTIONS] <WORKSPACE/APP> <ID>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <ID> The request id from `forculus access requests`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus access deny
Section titled “forculus access deny”Turn a request down. They aren't told.
Usage: forculus access deny [OPTIONS] <WORKSPACE/APP> <ID>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <ID> The request id from `forculus access requests`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus group
Section titled “forculus group”Manage a workspace's groups, to share apps with several people at once
Usage: forculus group [OPTIONS] <COMMAND>
Commands: create Make a group. For workspace owners and admins, and members whose custom role has groups.manage. list List a workspace's groups and who is in each add Add someone to a group. They needn't be in the workspace. remove Take someone out of a group. What it gave them ends within 60 seconds. delete Delete a group. Every app shared with it stops letting its people in within 60 seconds. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus group create
Section titled “forculus group create”Make a group. For workspace owners and admins, and members whose custom role hasgroups.manage.
Usage: forculus group create [OPTIONS] <WORKSPACE> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <NAME> Its name: lower-case letters, digits and single dashes. For example, finance.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus group list
Section titled “forculus group list”List a workspace's groups and who is in each
Usage: forculus group list [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus group add
Section titled “forculus group add”Add someone to a group. They needn't be in the workspace.
Usage: forculus group add [OPTIONS] <WORKSPACE> <NAME> <EMAIL>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <NAME> The group's name <EMAIL> Their email address
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus group remove
Section titled “forculus group remove”Take someone out of a group. What it gave them ends within 60 seconds.
Usage: forculus group remove [OPTIONS] <WORKSPACE> <NAME> <EMAIL>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <NAME> The group's name <EMAIL> Their email address
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus group delete
Section titled “forculus group delete”Delete a group. Every app shared with it stops letting its people in within 60seconds.
Usage: forculus group delete [OPTIONS] <WORKSPACE> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <NAME> The group's name
Options: --json Print machine-readable JSON instead of text --yes Confirm the delete. Putting it back means making the group again and sharing each app with it again. --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus role
Section titled “forculus role”Manage a workspace's custom roles: what a member may do, given to them or to agroup
Usage: forculus role [OPTIONS] <COMMAND>
Commands: list List a workspace's custom roles, what each lets its holders do, and who holds it create Make a custom role. For workspace owners and admins. An Enterprise feature, included on Business for early customers for a limited time. update Change what a custom role lets its holders do, or its description delete Delete a custom role nobody holds assign Give a member a custom role, or say which role a group gives the members in it unassign Take a member's custom role away, or stop a group giving one help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus role list
Section titled “forculus role list”List a workspace's custom roles, what each lets its holders do, and who holds it
Usage: forculus role list [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus role create
Section titled “forculus role create”Make a custom role. For workspace owners and admins. An Enterprise feature,included on Business for early customers for a limited time.
The permissions are apps.deploy, apps.share, members.manage, groups.manage,audit.view and billing.view. Someone with a custom role has exactly what theirroles name: leave out apps.deploy and they can't deploy.
Usage: forculus role create [OPTIONS] --permissions <PERMISSIONS> <WORKSPACE> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
<NAME> Its name: lower-case letters, digits and single dashes. For example, auditor.
Options: --json Print machine-readable JSON instead of text
--permissions <PERMISSIONS> What it lets its holders do, separated by commas. For example, audit.view,billing.view. Or none, for a role whose holders only open what's shared with them.
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
--description <DESCRIPTION> A line saying what it's for
-h, --help Print help (see a summary with '-h')forculus role update
Section titled “forculus role update”Change what a custom role lets its holders do, or its description
Usage: forculus role update [OPTIONS] <WORKSPACE> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <NAME> The role's name
Options: --json Print machine-readable JSON instead of text --permissions <PERMISSIONS> Everything it lets its holders do now, separated by commas, or none --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --description <DESCRIPTION> A line saying what it's for. An empty one takes it away. -h, --help Print helpforculus role delete
Section titled “forculus role delete”Delete a custom role nobody holds
Usage: forculus role delete [OPTIONS] <WORKSPACE> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <NAME> The role's name
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus role assign
Section titled “forculus role assign”Give a member a custom role, or say which role a group gives the members in it
Usage: forculus role assign <WORKSPACE> <ROLE> <EMAIL> forculus role assign <WORKSPACE> <ROLE> --group <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ROLE> The role's name [EMAIL] The member's email address
Options: --group <NAME> A group instead: every member of the workspace in it holds the role --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus role unassign
Section titled “forculus role unassign”Take a member's custom role away, or stop a group giving one
Usage: forculus role unassign <WORKSPACE> <EMAIL> forculus role unassign <WORKSPACE> --group <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme. [EMAIL] The member's email address
Options: --group <NAME> A group instead --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus policy
Section titled “forculus policy”Manage a workspace's publish policy: who may open its apps to the wholeworkspace, share them outside it, open public paths, make bypass tokens andagent credentials, and connect AI clients
Usage: forculus policy [OPTIONS] <COMMAND>
Commands: show Show a workspace's publish policy: who may do each act, and what you may do set Say who besides the owners may do an act. For workspace owners. Name nobody to keep it to the owners. An Enterprise feature, included on Business for early customers for a limited time. clear Take a rule off, so anyone who could do the act before may again breaches List what breaks the rules: shares, paths, tokens, credentials and AI clients made before a rule by someone it doesn't name. For workspace owners and admins. end End what breaks the rules, as taking each away by hand would. For workspace owners. Public paths close only from the dashboard. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus policy show
Section titled “forculus policy show”Show a workspace's publish policy: who may do each act, and what you may do
Usage: forculus policy show [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus policy set
Section titled “forculus policy set”Say who besides the owners may do an act. For workspace owners. Name nobody tokeep it to the owners. An Enterprise feature, included on Business for earlycustomers for a limited time.
What was done before and breaks the rule is kept and listed by `forculus policybreaches`, or ended now with --end.
Usage: forculus policy set [OPTIONS] <WORKSPACE> <ACT>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
<ACT> The act
Possible values: - publish: Open an app to everyone in the workspace, or share it with an email domain - share-outside: Share an app with someone outside the workspace - public-paths: Open a public path - bypass-tokens: Make a bypass token - agent-credentials: Mint an agent's credential - ai-clients: Let an app take AI clients, or connect one to it
Options: --admins Admins may
--json Print machine-readable JSON instead of text
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
--members Every member may
--roles <ROLES> Members holding one of these custom roles may, separated by commas
--end End now whatever breaks the rule
-h, --help Print help (see a summary with '-h')forculus policy clear
Section titled “forculus policy clear”Take a rule off, so anyone who could do the act before may again
Usage: forculus policy clear [OPTIONS] <WORKSPACE> <ACT>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
<ACT> The act whose rule to take off
Possible values: - publish: Open an app to everyone in the workspace, or share it with an email domain - share-outside: Share an app with someone outside the workspace - public-paths: Open a public path - bypass-tokens: Make a bypass token - agent-credentials: Mint an agent's credential - ai-clients: Let an app take AI clients, or connect one to it
Options: --json Print machine-readable JSON instead of text
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
-h, --help Print help (see a summary with '-h')forculus policy breaches
Section titled “forculus policy breaches”List what breaks the rules: shares, paths, tokens, credentials and AI clientsmade before a rule by someone it doesn't name. For workspace owners and admins.
Usage: forculus policy breaches [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus policy end
Section titled “forculus policy end”End what breaks the rules, as taking each away by hand would. For workspaceowners. Public paths close only from the dashboard.
Usage: forculus policy end [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --act <ACTS> Only what breaks the rules on these acts, separated by commas
Possible values: - publish: Open an app to everyone in the workspace, or share it with an email domain - share-outside: Share an app with someone outside the workspace - public-paths: Open a public path - bypass-tokens: Make a bypass token - agent-credentials: Mint an agent's credential - ai-clients: Let an app take AI clients, or connect one to it
--json Print machine-readable JSON instead of text
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
-h, --help Print help (see a summary with '-h')forculus token
Section titled “forculus token”Manage bypass tokens, which let scripts and services call an app
Usage: forculus token [OPTIONS] <COMMAND>
Commands: create Create a bypass token for a script or service. We show the secret once. list List an app's tokens. Secrets are never shown. revoke Revoke a token. It stops working on the next request. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus token create
Section titled “forculus token create”Create a bypass token for a script or service. We show the secret once.
Usage: forculus token create [OPTIONS] <WORKSPACE/APP> <NAME>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <NAME> A name to recognise it by. For example, ci or nightly-sync.
Options: --json Print machine-readable JSON instead of text --role <ROLE> The role your app sees for the caller [default: viewer] [possible values: viewer, editor] --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --days <DAYS> How many days it lasts, up to 30, and never past the end of your CLI session's 30 days. Signing out doesn't end it: revoke it, or use `logout --everywhere --tokens`. For a longer-lived token, use the dashboard. [default: 30] -h, --help Print helpforculus token list
Section titled “forculus token list”List an app's tokens. Secrets are never shown.
Usage: forculus token list [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus token revoke
Section titled “forculus token revoke”Revoke a token. It stops working on the next request.
Usage: forculus token revoke [OPTIONS] <WORKSPACE/APP> <ID>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <ID> The token id from `forculus token list`. It starts with bt_.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus agent
Section titled “forculus agent”Manage agents: named callers of a workspace's own, each reaching the apps yougrant it with credentials of its own, and named as itself in the audit log
Usage: forculus agent [OPTIONS] <COMMAND>
Commands: create Make an agent in a workspace. It reaches nothing until you grant it an app. list List a workspace's live agents, with the apps granted to them, their credentials and when each was last used grant Let an agent reach an app. It takes effect on the agent's next request. revoke Take an app away from an agent. Its next request is refused, and open connections end within 15 seconds. token Mint a credential for an agent, or revoke one with --revoke. We show a new secret once. rename Rename an agent. Its id, its credentials and the apps granted to it stay as they are. end End an agent for good. Its credentials stop working and its apps are taken away. It can't be undone, so it asks first. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus agent create
Section titled “forculus agent create”Make an agent in a workspace. It reaches nothing until you grant it an app.
Usage: forculus agent create [OPTIONS] <WORKSPACE> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <NAME> A name to recognise it by in the log. For example, release-bot.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus agent list
Section titled “forculus agent list”List a workspace's live agents, with the apps granted to them, their credentialsand when each was last used
Usage: forculus agent list [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --all List ended agents too, after the live ones --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus agent grant
Section titled “forculus agent grant”Let an agent reach an app. It takes effect on the agent's next request.
Usage: forculus agent grant [OPTIONS] <WORKSPACE/APP> <AGENT>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <AGENT> The agent's name or id
Options: --json Print machine-readable JSON instead of text --role <ROLE> The role the app sees for the agent [default: viewer] [possible values: viewer, editor] --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus agent revoke
Section titled “forculus agent revoke”Take an app away from an agent. Its next request is refused, and openconnections end within 15 seconds.
Usage: forculus agent revoke [OPTIONS] <WORKSPACE/APP> <AGENT>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <AGENT> The agent's name or id
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus agent token
Section titled “forculus agent token”Mint a credential for an agent, or revoke one with --revoke. We show a newsecret once.
Usage: forculus agent token [OPTIONS] <WORKSPACE> <AGENT>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <AGENT> The agent's name or id
Options: --days <DAYS> How many days it lasts, up to 30, and never past the end of your CLI session's 30 days. Signing out doesn't end it: revoke it, or use `logout --everywhere --tokens`. For a longer-lived credential, use the dashboard. [default: 30] --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --revoke <ID> Revoke this credential instead, by its id from `forculus agent list`. It starts with ac_. It stops working on the next request. -h, --help Print helpforculus agent rename
Section titled “forculus agent rename”Rename an agent. Its id, its credentials and the apps granted to it stay as theyare.
Usage: forculus agent rename [OPTIONS] <WORKSPACE> <AGENT> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <AGENT> The agent's name or id <NAME> Its new name. For example, release-bot.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus agent end
Section titled “forculus agent end”End an agent for good. Its credentials stop working and its apps are taken away.It can't be undone, so it asks first.
Usage: forculus agent end [OPTIONS] <WORKSPACE> <AGENT>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <AGENT> The agent's name or id
Options: --json Print machine-readable JSON instead of text --yes End it without asking. Needed where there's no terminal to ask at. --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus secret
Section titled “forculus secret”Manage third-party credentials. We add them to an app's outbound requests.
Usage: forculus secret [OPTIONS] <COMMAND>
Commands: set Store a credential for an app's outbound requests. Paste it at the hidden prompt or pipe it on stdin, or pass --value. list List an app's secrets and where each is sent. Values are never shown. remove Remove a secret. The app's requests stop carrying it within 10 seconds. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus secret set
Section titled “forculus secret set”Store a credential for an app's outbound requests. Paste it at the hidden promptor pipe it on stdin, or pass --value.
Usage: forculus secret set [OPTIONS] --host <HOST> --header <HEADER> <WORKSPACE/APP> <NAME>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <NAME> Its name in UPPER_SNAKE_CASE. For example, STRIPE_KEY.
Options: --host <HOST> Only add it to requests to exactly this host --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --header <HEADER> The header it goes in. For example, Authorization. --format <FORMAT> How to build the header value. For example, "Bearer {value}". --value <VALUE> The secret. Piping it on stdin is safer, because flags end up in your shell history. -h, --help Print helpforculus secret list
Section titled “forculus secret list”List an app's secrets and where each is sent. Values are never shown.
Usage: forculus secret list [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus secret remove
Section titled “forculus secret remove”Remove a secret. The app's requests stop carrying it within 10 seconds.
Usage: forculus secret remove [OPTIONS] <WORKSPACE/APP> <NAME>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <NAME> The secret's name
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus egress
Section titled “forculus egress”Choose which hosts an app may send requests to
Usage: forculus egress [OPTIONS] <COMMAND>
Commands: list Show whether an app is held to its list, and the hosts on it allow Add a host the app may send requests to. Takes effect within 10 seconds once the list is on. deny Take a host off the app's list. Requests to it stop within 10 seconds. on Hold the app to its list: requests to any other host are refused. Within 10 seconds. off Let the app send requests to any host again. Within 10 seconds. usage Show where the app sent requests over the last 30 days, busiest host first, with what its list refused. For the app's editors and owners, and the workspace's owners and admins. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus egress list
Section titled “forculus egress list”Show whether an app is held to its list, and the hosts on it
Usage: forculus egress list [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus egress allow
Section titled “forculus egress allow”Add a host the app may send requests to. Takes effect within 10 seconds once thelist is on.
Usage: forculus egress allow [OPTIONS] <WORKSPACE/APP> <HOST>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <HOST> A host like api.stripe.com, or *.stripe.com for every host under stripe.com. Quote a pattern with * so your shell leaves it alone.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus egress deny
Section titled “forculus egress deny”Take a host off the app's list. Requests to it stop within 10 seconds.
Usage: forculus egress deny [OPTIONS] <WORKSPACE/APP> <HOST>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <HOST> The host or pattern, as `forculus egress list` shows it
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus egress on
Section titled “forculus egress on”Hold the app to its list: requests to any other host are refused. Within 10seconds.
Usage: forculus egress on [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus egress off
Section titled “forculus egress off”Let the app send requests to any host again. Within 10 seconds.
Usage: forculus egress off [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus egress usage
Section titled “forculus egress usage”Show where the app sent requests over the last 30 days, busiest host first, withwhat its list refused. For the app's editors and owners, and the workspace'sowners and admins.
Usage: forculus egress usage [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus ai
Section titled “forculus ai”Share the workspace's AI provider keys with apps, each with a monthly budget
Usage: forculus ai [OPTIONS] <COMMAND>
Commands: keys List the workspace's AI keys, the apps each is granted to, and this month's spend key Store or remove the workspace's key for a provider. Workspace owners only. grant Let an app use the workspace's key, up to a monthly budget in dollars. Owners only. revoke Stop an app using the workspace's key. Its next request goes without it. show Show an app's AI budgets and what it has spent this month help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus ai keys
Section titled “forculus ai keys”List the workspace's AI keys, the apps each is granted to, and this month'sspend
Usage: forculus ai keys [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus ai key
Section titled “forculus ai key”Store or remove the workspace's key for a provider. Workspace owners only.
Usage: forculus ai key [OPTIONS] <COMMAND>
Commands: set Store the workspace's key for a provider, replacing any it had. Paste it at the hidden prompt or pipe it on stdin. It is never shown again. remove Remove the workspace's key for a provider, and every app's grant of it. Asks first. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus ai key set
Section titled “forculus ai key set”Store the workspace's key for a provider, replacing any it had. Paste it at thehidden prompt or pipe it on stdin. It is never shown again.
Usage: forculus ai key set [OPTIONS] <WORKSPACE> <PROVIDER>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <PROVIDER> Whose key: anthropic, openai, gemini, mistral, groq, cohere, azure or bedrock [possible values: anthropic, openai, gemini, mistral, groq, cohere, azure, bedrock]
Options: --endpoint <RESOURCE> Azure OpenAI only: the resource the key is for, by name or endpoint. For example, acme or https://acme.openai.azure.com --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --region <REGION> Amazon Bedrock only: the region the key is used in. For example, us-east-1. -h, --help Print helpforculus ai key remove
Section titled “forculus ai key remove”Remove the workspace's key for a provider, and every app's grant of it. Asksfirst.
Usage: forculus ai key remove [OPTIONS] <WORKSPACE> <PROVIDER>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <PROVIDER> Whose key: anthropic, openai, gemini, mistral, groq, cohere, azure or bedrock [possible values: anthropic, openai, gemini, mistral, groq, cohere, azure, bedrock]
Options: --json Print machine-readable JSON instead of text --yes Remove it without asking. Needed where there's no terminal to ask at. --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus ai grant
Section titled “forculus ai grant”Let an app use the workspace's key, up to a monthly budget in dollars. Ownersonly.
Usage: forculus ai grant [OPTIONS] --budget <BUDGET> <WORKSPACE/APP> <PROVIDER>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <PROVIDER> Whose key: anthropic, openai, gemini, mistral, groq, cohere, azure or bedrock [possible values: anthropic, openai, gemini, mistral, groq, cohere, azure, bedrock]
Options: --budget <BUDGET> The most it may spend in a calendar month (UTC), in dollars. For example, 25 or 12.50. --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus ai revoke
Section titled “forculus ai revoke”Stop an app using the workspace's key. Its next request goes without it.
Usage: forculus ai revoke [OPTIONS] <WORKSPACE/APP> <PROVIDER>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <PROVIDER> Whose key: anthropic, openai, gemini, mistral, groq, cohere, azure or bedrock [possible values: anthropic, openai, gemini, mistral, groq, cohere, azure, bedrock]
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus ai show
Section titled “forculus ai show”Show an app's AI budgets and what it has spent this month
Usage: forculus ai show [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus postgres
Section titled “forculus postgres”Connect a Postgres database you already have, like Neon, Supabase or RDS, andgive it to apps. Its password stays with us. Apps query it through the platform.
Usage: forculus postgres [OPTIONS] <COMMAND>
Commands: list List the workspace's Postgres connections, the apps given each, and how the last check went. For owners and admins. add Connect a Postgres database by its URL, like postgres://user:password@host:5432/db. Paste the URL at the hidden prompt or pipe it on stdin. We try it first, and keep the password sealed: no app or person sees it again. Owners only. rotate Give a connection a new password, after you change it at the database. Paste it at the hidden prompt or pipe it on stdin. Apps keep working: we try it before we switch. Owners only. update Point a connection at a new URL, or change how its certificate is checked. With --url, paste the URL at the hidden prompt or pipe it on stdin. Owners only. check Try a connection again now and say what went wrong, if anything. For owners and admins. remove Remove a connection, and every app's grant of it. Their queries stop within 10 seconds. Your database and its data aren't touched. Asks first. grant Let an app query a connection, at http://postgres.forculus.internal/<name>/query. Owners only. revoke Stop an app reaching a connection. Its queries stop within 10 seconds. show Show the connections an app was given. For anyone who can edit the app. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus postgres list
Section titled “forculus postgres list”List the workspace's Postgres connections, the apps given each, and how the lastcheck went. For owners and admins.
Usage: forculus postgres list [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus postgres add
Section titled “forculus postgres add”Connect a Postgres database by its URL, likepostgres://user:password@host:5432/db. Paste the URL at the hidden prompt orpipe it on stdin. We try it first, and keep the password sealed: no app orperson sees it again. Owners only.
Usage: forculus postgres add [OPTIONS] <WORKSPACE> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
<NAME> What apps call it, like main or analytics: lowercase letters, digits and dashes
Options: --json Print machine-readable JSON instead of text
--tls <TLS> How the database's certificate is checked. verify-ca and verify-full need --ca-file
Possible values: - require: Encrypted, with the certificate checked as Cloudflare checks it by default - verify-ca: Also checks the certificate was signed by the authority in --ca-file - verify-full: Also checks the certificate names the host
[default: require]
--ca-file <FILE> The certificate authority that signed the database's certificate, as a PEM file
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
-h, --help Print help (see a summary with '-h')forculus postgres rotate
Section titled “forculus postgres rotate”Give a connection a new password, after you change it at the database. Paste itat the hidden prompt or pipe it on stdin. Apps keep working: we try it before weswitch. Owners only.
Usage: forculus postgres rotate [OPTIONS] <WORKSPACE> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <NAME> The connection's name
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus postgres update
Section titled “forculus postgres update”Point a connection at a new URL, or change how its certificate is checked. With--url, paste the URL at the hidden prompt or pipe it on stdin. Owners only.
Usage: forculus postgres update [OPTIONS] <WORKSPACE> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
<NAME> The connection's name
Options: --json Print machine-readable JSON instead of text
--url Read a new URL, with its own user and password
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
--tls <TLS> How the database's certificate is checked. verify-ca and verify-full need --ca-file
Possible values: - require: Encrypted, with the certificate checked as Cloudflare checks it by default - verify-ca: Also checks the certificate was signed by the authority in --ca-file - verify-full: Also checks the certificate names the host
--ca-file <FILE> The certificate authority that signed the database's certificate, as a PEM file
-h, --help Print help (see a summary with '-h')forculus postgres check
Section titled “forculus postgres check”Try a connection again now and say what went wrong, if anything. For owners andadmins.
Usage: forculus postgres check [OPTIONS] <WORKSPACE> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <NAME> The connection's name
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus postgres remove
Section titled “forculus postgres remove”Remove a connection, and every app's grant of it. Their queries stop within 10seconds. Your database and its data aren't touched. Asks first.
Usage: forculus postgres remove [OPTIONS] <WORKSPACE> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <NAME> The connection's name
Options: --json Print machine-readable JSON instead of text --yes Remove it without asking. Needed where there's no terminal to ask at. --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus postgres grant
Section titled “forculus postgres grant”Let an app query a connection, athttp://postgres.forculus.internal/<name>/query. Owners only.
Usage: forculus postgres grant [OPTIONS] <WORKSPACE/APP> <NAME>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <NAME> The connection's name
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus postgres revoke
Section titled “forculus postgres revoke”Stop an app reaching a connection. Its queries stop within 10 seconds.
Usage: forculus postgres revoke [OPTIONS] <WORKSPACE/APP> <NAME>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <NAME> The connection's name
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus postgres show
Section titled “forculus postgres show”Show the connections an app was given. For anyone who can edit the app.
Usage: forculus postgres show [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus network
Section titled “forculus network”Let apps reach systems inside your company's network, and see the fixedaddresses they send from. Enterprise, where the platform has private networksswitched on.
Usage: forculus network [OPTIONS] <COMMAND>
Commands: list List the workspace's networks, its services and the apps that reach each, and the fixed addresses its apps send from add Add a network and print the command that runs its connector inside your network. Owners and admins, on Enterprise, where the platform has private networks switched on. `network list` says when it hasn't. connector Print the command that runs a network's connector again. Needs a sign-in in the last few minutes. Owners and admins. remove Remove a network that has no services left on it. Asks first. service Add or remove a service: one host on a network, and its ports grant Let an app reach a service. It takes effect within 10 seconds. Owners and admins. revoke Stop an app reaching a service. Anyone who can edit the app. show List the services an app reaches help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus network list
Section titled “forculus network list”List the workspace's networks, its services and the apps that reach each, andthe fixed addresses its apps send from
Usage: forculus network list [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus network add
Section titled “forculus network add”Add a network and print the command that runs its connector inside your network.Owners and admins, on Enterprise, where the platform has private networksswitched on. `network list` says when it hasn't.
Usage: forculus network add [OPTIONS] <WORKSPACE> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <NAME> A name for it: lowercase letters, digits and dashes. For example, office.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus network connector
Section titled “forculus network connector”Print the command that runs a network's connector again. Needs a sign-in in thelast few minutes. Owners and admins.
Usage: forculus network connector [OPTIONS] <WORKSPACE> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <NAME> The network's name
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus network remove
Section titled “forculus network remove”Remove a network that has no services left on it. Asks first.
Usage: forculus network remove [OPTIONS] <WORKSPACE> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <NAME> The network's name
Options: --json Print machine-readable JSON instead of text --yes Remove it without asking. Needed where there's no terminal to ask at. --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus network service
Section titled “forculus network service”Add or remove a service: one host on a network, and its ports
Usage: forculus network service [OPTIONS] <COMMAND>
Commands: add Put a service on a network: a host name or address on it, and the ports an app's https and http requests go to. Owners and admins, on Enterprise, where the platform has private networks switched on. remove Remove a service. Every app that reaches it stops on its next request. Asks first. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus network service add
Section titled “forculus network service add”Put a service on a network: a host name or address on it, and the ports an app'shttps and http requests go to. Owners and admins, on Enterprise, where theplatform has private networks switched on.
Usage: forculus network service add [OPTIONS] --network <NETWORK> --host <HOST> <WORKSPACE> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
<NAME> A name for it: lowercase letters, digits and dashes. For example, erp.
Options: --json Print machine-readable JSON instead of text
--network <NETWORK> The network it's on
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
--host <HOST> Its host, as your apps will ask for it: a name, or an address on your network. For example, erp.corp.example or 10.0.4.12.
--https-port <HTTPS_PORT> The port an app's https requests go to. For example, 443.
--http-port <HTTP_PORT> The port an app's plain http requests go to. For example, 80.
--tls <TLS> How its certificate is checked over https
Possible values: - full: Checked in full: signed by a public CA, for the host's name - ca: Its chain checked, and not the name on it - off: Not checked
[default: full]
-h, --help Print help (see a summary with '-h')forculus network service remove
Section titled “forculus network service remove”Remove a service. Every app that reaches it stops on its next request. Asksfirst.
Usage: forculus network service remove [OPTIONS] <WORKSPACE> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <NAME> The service's name
Options: --json Print machine-readable JSON instead of text --yes Remove it without asking. Needed where there's no terminal to ask at. --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus network grant
Section titled “forculus network grant”Let an app reach a service. It takes effect within 10 seconds. Owners andadmins.
Usage: forculus network grant [OPTIONS] <WORKSPACE/APP> <SERVICE>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <SERVICE> The service's name
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus network revoke
Section titled “forculus network revoke”Stop an app reaching a service. Anyone who can edit the app.
Usage: forculus network revoke [OPTIONS] <WORKSPACE/APP> <SERVICE>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <SERVICE> The service's name
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus network show
Section titled “forculus network show”List the services an app reaches
Usage: forculus network show [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus env
Section titled “forculus env”Manage an app's config values. Put credentials in `forculus secret set` instead.
Usage: forculus env [OPTIONS] <COMMAND>
Commands: set Set one or more NAME=value pairs. We redeploy the live version with them. Values your build bakes in change on the next deploy. remove Remove variables. We redeploy the live version without them. Values your build baked in stay until the next deploy. list List an app's variables and their values help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus env set
Section titled “forculus env set”Set one or more NAME=value pairs. We redeploy the live version with them. Valuesyour build bakes in change on the next deploy.
Usage: forculus env set [OPTIONS] <WORKSPACE/APP> <PAIRS>...
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <PAIRS>... NAME=value. Repeat for more.
Options: --allow-sensitive-name Allow a name that looks like a credential. Values we know are credentials are still refused. --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus env remove
Section titled “forculus env remove”Remove variables. We redeploy the live version without them. Values your buildbaked in stay until the next deploy.
Usage: forculus env remove [OPTIONS] <WORKSPACE/APP> <NAMES>...
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <NAMES>... The variable names
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus env list
Section titled “forculus env list”List an app's variables and their values
Usage: forculus env list [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus db
Section titled “forculus db”Export an app's database or run a SQL statement on it
Usage: forculus db [OPTIONS] <COMMAND>
Commands: export Export an app's database as SQL to a file or stdout. Workspace owners only. The database pauses during the export, so run it when the app is quiet. restore Put an app's database back as it was at a moment in the last 30 days. Workspace owners only. It replaces what's there now, so it prints a bookmark that undoes it. query Query an app's database and print the rows as a table, a page at a time. Read only unless you add --write. Workspace owners only, except that admins can run DELETE, DROP TABLE and DROP INDEX with --write. exec Run one SQL statement on an app's database and print the result. Workspace owners can run any statement. Admins can run DELETE, DROP TABLE and DROP INDEX. While databases are over the plan's limit, those three are all anyone can run. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus db export
Section titled “forculus db export”Export an app's database as SQL to a file or stdout. Workspace owners only. Thedatabase pauses during the export, so run it when the app is quiet.
Usage: forculus db export [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text -o, --out <OUT> Where to save it. Defaults to <workspace>-<app>.sql in the current directory. - is stdout. --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --stdout Write to stdout instead of a file -h, --help Print helpforculus db restore
Section titled “forculus db restore”Put an app's database back as it was at a moment in the last 30 days. Workspaceowners only. It replaces what's there now, so it prints a bookmark that undoesit.
Usage: forculus db restore [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --to <TIME> When to go back to: a time like 2026-10-03T14:00:00Z, or how long ago, like 90m, 6h or 2d --bookmark <BOOKMARK> A bookmark an earlier restore printed, to undo it --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --yes Confirm the restore. Everything written to the database after that moment is replaced. Without it, nothing changes, and a time shows the bookmark it goes back to. -h, --help Print helpforculus db query
Section titled “forculus db query”Query an app's database and print the rows as a table, a page at a time. Readonly unless you add --write. Workspace owners only, except that admins can runDELETE, DROP TABLE and DROP INDEX with --write.
Usage: forculus db query [OPTIONS] <WORKSPACE/APP> <STATEMENT>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <STATEMENT> One statement in quotes, with no comments
Options: --json Print machine-readable JSON instead of text --write Run a statement that changes the database. Without it, only one that reads runs. --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --limit <LIMIT> Rows to show, up to 1,000 [default: 100] --offset <OFFSET> Rows to skip, to see the next page [default: 0] --csv Print the rows as CSV, up to 10,000 of them, rather than a table -o, --out <OUT> With --csv, the file to save it to. Defaults to stdout. -h, --help Print helpforculus db exec
Section titled “forculus db exec”Run one SQL statement on an app's database and print the result. Workspaceowners can run any statement. Admins can run DELETE, DROP TABLE and DROP INDEX.While databases are over the plan's limit, those three are all anyone can run.
Usage: forculus db exec [OPTIONS] <WORKSPACE/APP> <STATEMENT>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <STATEMENT> One statement in quotes, with no comments
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus domain
Section titled “forculus domain”Manage an app's custom domains, like app.example.com
Usage: forculus domain [OPTIONS] <COMMAND>
Commands: add Add a hostname for an app. We print the DNS records to add. It works once they're verified. list List an app's custom domains and where each stands remove Remove a custom domain. It stops working within 60 seconds. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus domain add
Section titled “forculus domain add”Add a hostname for an app. We print the DNS records to add. It works oncethey're verified.
Usage: forculus domain add [OPTIONS] <WORKSPACE/APP> <HOSTNAME>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <HOSTNAME> The hostname. For example, app.example.com.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus domain list
Section titled “forculus domain list”List an app's custom domains and where each stands
Usage: forculus domain list [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus domain remove
Section titled “forculus domain remove”Remove a custom domain. It stops working within 60 seconds.
Usage: forculus domain remove [OPTIONS] <WORKSPACE/APP> <HOSTNAME>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <HOSTNAME> The hostname
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus files
Section titled “forculus files”List, download, upload or delete the files an app keeps
Usage: forculus files [OPTIONS] <COMMAND>
Commands: ls List an app's files, or the ones whose names start with a prefix get Download one file to the current directory, to --out, or to stdout. Workspace owners only. put Upload a file as one of the app's, replacing any with the same name. Workspace owners only, up to 25 MB. Use - to read it from stdin. rm Delete one of an app's files. This can't be undone. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus files ls
Section titled “forculus files ls”List an app's files, or the ones whose names start with a prefix
Usage: forculus files ls [OPTIONS] <WORKSPACE/APP> [PREFIX]
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. [PREFIX] Only names that start with this. For example, reports/. [default: ""]
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus files get
Section titled “forculus files get”Download one file to the current directory, to --out, or to stdout. Workspaceowners only.
Usage: forculus files get [OPTIONS] <WORKSPACE/APP> <PATH>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <PATH> The file's name in the app, exactly as `files ls --json` lists it. For example, reports/2026/october.csv.
Options: --json Print machine-readable JSON instead of text -o, --out <OUT> Where to save it. Defaults to the last part of its name. - writes it to stdout. --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --stdout Write it to stdout instead of a file --force Replace a file that's already there -h, --help Print helpforculus files put
Section titled “forculus files put”Upload a file as one of the app's, replacing any with the same name. Workspaceowners only, up to 25 MB. Use - to read it from stdin.
Usage: forculus files put [OPTIONS] <WORKSPACE/APP> <PATH> <FILE>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <PATH> The name it gets in the app. For example, reports/2026/october.csv. <FILE> The file on this computer
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus files rm
Section titled “forculus files rm”Delete one of an app's files. This can't be undone.
Usage: forculus files rm [OPTIONS] <WORKSPACE/APP> <PATH>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <PATH> The file's name in the app, exactly as the app wrote it: any name `files ls --json` lists, spaces and all
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus kv
Section titled “forculus kv”Read, write or delete the keys an app keeps in key-value storage
Usage: forculus kv [OPTIONS] <COMMAND>
Commands: status How much the app keeps, and how many keys, as last measured ls List an app's keys, or the ones that start with a prefix get Print a key's value, or save it with --out. Workspace owners only. put Set a key, replacing any value it had. Workspace owners only, up to 25 MB. rm Delete one of an app's keys. This can't be undone. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus kv status
Section titled “forculus kv status”How much the app keeps, and how many keys, as last measured
Usage: forculus kv status [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus kv ls
Section titled “forculus kv ls”List an app's keys, or the ones that start with a prefix
Usage: forculus kv ls [OPTIONS] <WORKSPACE/APP> [PREFIX]
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. [PREFIX] Only keys that start with this. For example, user: [default: ""]
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus kv get
Section titled “forculus kv get”Print a key's value, or save it with --out. Workspace owners only.
Usage: forculus kv get [OPTIONS] <WORKSPACE/APP> <KEY>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <KEY> The key, exactly as `kv ls` lists it
Options: --json Print machine-readable JSON instead of text -o, --out <OUT> Save the value to this file instead of printing it --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus kv put
Section titled “forculus kv put”Set a key, replacing any value it had. Workspace owners only, up to 25 MB.
Usage: forculus kv put [OPTIONS] <WORKSPACE/APP> <KEY> [VALUE]
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <KEY> The key. 1 to 512 bytes. It can't be . or have a .. part between slashes. [VALUE] The value. Leave it out to use --file.
Options: --file <FILE> Read the value from this file. Use - to read it from stdin. --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus kv rm
Section titled “forculus kv rm”Delete one of an app's keys. This can't be undone.
Usage: forculus kv rm [OPTIONS] <WORKSPACE/APP> <KEY>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <KEY> The key, exactly as `kv ls` lists it
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus queue
Section titled “forculus queue”See how an app's queue is doing, or send it a message
Usage: forculus queue [OPTIONS] <COMMAND>
Commands: status Where its messages go, how the last batch went, and how many are waiting send Send one message to the app's queue, as its code would. For anyone who can deploy the app. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus queue status
Section titled “forculus queue status”Where its messages go, how the last batch went, and how many are waiting
Usage: forculus queue status [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus queue send
Section titled “forculus queue send”Send one message to the app's queue, as its code would. For anyone who candeploy the app.
Usage: forculus queue send [OPTIONS] <WORKSPACE/APP> <JSON>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll. <JSON> The message, as a JSON object. For example, '{"job":"report"}'. Use - to read it from stdin.
Options: --delay <SECONDS> Wait this many seconds before it's sent to the app, up to 86400 --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus audit
Section titled “forculus audit”Show a workspace's audit log, newest first. For owners and admins, members whosecustom role has audit.view, and an app's owners with --app.
Usage: forculus audit [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --app <APP> Only this app, by slug or <workspace>/<app>. Deleted apps that had the same name show up too, marked (deleted). --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --limit <LIMIT> How many entries to show [default: 50] --before <BEFORE> Only entries before this date or RFC 3339 time. A date like 2026-09-01 means midnight UTC. When there are older entries, we print the flags for the next page. --before-id <BEFORE_ID> With --before: the id of the last entry you have, so entries with the same time aren't skipped --csv Print the entries as CSV for a spreadsheet, oldest first, with a header line: time, action, decision, reason, status, actor, app, method, path, detail and id. A page read with --before is older than the one before it, so join pages in reverse order. An Enterprise feature, included on Business for early customers for a limited time. -h, --help Print helpforculus insights
Section titled “forculus insights”Show who opens a workspace's apps: people, opens and when each app was lastopened, the apps nobody opened in 30, 60 or 90 days, and apps whose owners haveall left. For owners and admins, members whose custom role has audit.view, andan app's owners with --app.
Counted from the audit log's requests by signed-in people, up to an hour behindit. An open is a visit: someone's first request to an app, or the first after 30minutes without one.
Usage: forculus insights [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --app <APP> Only this app, by slug or <workspace>/<app>. Its owners see its last 30 days.
--json Print machine-readable JSON instead of text
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
--days <DAYS> How many days back to count, up to today. Your plan sets how far back you can go: 30 days on Free, 90 on Team, 365 on Business and Enterprise. Defaults to 30.
[possible values: 7, 30, 90, 365]
--csv <KIND> Print a CSV for a spreadsheet instead: apps (a line per app) or people (a line per person and app they opened)
[possible values: apps, people]
-h, --help Print help (see a summary with '-h')forculus webhook
Section titled “forculus webhook”Send a workspace's events to a URL or a Slack channel. For owners and admins.
Usage: forculus webhook [OPTIONS] <COMMAND>
Commands: add Add a webhook. We sign every event we send it and show the signing secret once. With --slack, each event is a line in a Slack channel: paste its incoming webhook URL at the prompt or pipe it on stdin, since the URL lets anyone post there. rename Name a webhook or Slack channel, or give it a new name. An empty name takes it off. list List a workspace's webhooks and Slack channels remove Remove a webhook or Slack channel. Nothing more is sent to it. edit Change which events a webhook or Slack channel gets, or turn it on or off. Turning one on again starts it from now: what happened while it was off isn't sent. test Send a test event to a webhook now and say how it went. Exits with 1 when it wasn't delivered. deliveries List the events sent to a webhook or Slack channel in the last week, newest first, up to 50: delivered, failed or still being tried, and why a try failed help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus webhook add
Section titled “forculus webhook add”Add a webhook. We sign every event we send it and show the signing secret once.With --slack, each event is a line in a Slack channel: paste its incomingwebhook URL at the prompt or pipe it on stdin, since the URL lets anyone postthere.
Usage: forculus webhook add [OPTIONS] <WORKSPACE> [URL]
Arguments: <WORKSPACE> The workspace slug. For example, acme. [URL] Where to send events: an https URL. Leave it out with --slack.
Options: --json Print machine-readable JSON instead of text --slack The URL is a Slack incoming webhook, https://hooks.slack.com/services/... --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --event <EVENT> An event to send, like app.deploy or grant.put. Repeat for more. Leave it out for every event, or with --slack for deploys, shares, new members, new tokens, refused visits and requests for access. --name <NAME> A name to tell it apart from others by, like "deploys to ops". At most 60 characters. -h, --help Print helpforculus webhook rename
Section titled “forculus webhook rename”Name a webhook or Slack channel, or give it a new name. An empty name takes itoff.
Usage: forculus webhook rename [OPTIONS] <WORKSPACE> <ID> <NAME>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The webhook's id from `forculus webhook list` <NAME> Its new name. At most 60 characters.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus webhook list
Section titled “forculus webhook list”List a workspace's webhooks and Slack channels
Usage: forculus webhook list [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus webhook remove
Section titled “forculus webhook remove”Remove a webhook or Slack channel. Nothing more is sent to it.
Usage: forculus webhook remove [OPTIONS] <WORKSPACE> <ID>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The webhook's id from `forculus webhook list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus webhook edit
Section titled “forculus webhook edit”Change which events a webhook or Slack channel gets, or turn it on or off.Turning one on again starts it from now: what happened while it was off isn'tsent.
Usage: forculus webhook edit [OPTIONS] <WORKSPACE> <ID>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The webhook's id from `forculus webhook list`
Options: --event <EVENT> The events it gets from now, in place of the ones it had. Repeat for more. For example, --event app.deploy --event access_request.create. --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --on Turn it on, or back on after it failed for a day --off Pause it. Nothing is sent to it until it's on again. -h, --help Print helpforculus webhook test
Section titled “forculus webhook test”Send a test event to a webhook now and say how it went. Exits with 1 when itwasn't delivered.
Usage: forculus webhook test [OPTIONS] <WORKSPACE> <ID>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The webhook's id from `forculus webhook list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus webhook deliveries
Section titled “forculus webhook deliveries”List the events sent to a webhook or Slack channel in the last week, newestfirst, up to 50: delivered, failed or still being tried, and why a try failed
Usage: forculus webhook deliveries [OPTIONS] <WORKSPACE> <ID>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The webhook's id from `forculus webhook list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus audit-stream
Section titled “forculus audit-stream”Stream a workspace's whole audit log to Splunk, Datadog, a URL or an S3 bucket.Owners set streams up, and owners and admins list them. An Enterprise feature,included on Business for early customers for a limited time.
Usage: forculus audit-stream [OPTIONS] <COMMAND>
Commands: add Start streaming the audit log somewhere. Give one of --splunk, --datadog, --http or --s3. The credential is asked for at the prompt or read from stdin, so it stays out of shell history: the Splunk token, the Datadog API key, the secret access key, or with --header the header's value. list List a workspace's audit log streams pause Stop a stream for now. What happens meanwhile waits in the log. resume Turn a stream back on. It sends what it missed, as far back as a week. test Send a test entry now and say how it went failed List the batches that failed for a day and wait to be sent again, kept for a week retry Send failed batches again: every one, or one with --batch. They go once the stream is on. remove Remove a stream. Nothing more is sent to it, and what it hadn't sent goes with it. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus audit-stream add
Section titled “forculus audit-stream add”Start streaming the audit log somewhere. Give one of --splunk, --datadog, --httpor --s3. The credential is asked for at the prompt or read from stdin, so itstays out of shell history: the Splunk token, the Datadog API key, the secretaccess key, or with --header the header's value.
Usage: forculus audit-stream add [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --splunk <URL> A Splunk HTTP Event Collector, like https://http-inputs-acme.splunkcloud.com or https://splunk.example.com:8088 --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --index <INDEX> With --splunk: the index to send to, if not the token's default --datadog <SITE> A Datadog site: datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com or ddog-gov.com --tags <TAGS> With --datadog: tags to add to every entry, like env:prod,team:security --http <URL> A URL that takes each batch as a signed JSON array. We show the signing secret once. --header <NAME> With --http: a header to send with each batch, like Authorization. Its value is asked for like a credential. --s3 <BUCKET> An S3 bucket: AWS's, R2's with --endpoint, or another that speaks S3 --region <REGION> With --s3: the bucket's region, like us-east-1, or auto for R2 --access-key-id <ACCESS_KEY_ID> With --s3: the access key ID. The secret access key is asked for. --endpoint <URL> With --s3: where the bucket is, if not AWS. For R2, https://<account id>.r2.cloudflarestorage.com. --prefix <PREFIX> With --s3: a folder to write under, like audit/forculus/ -h, --help Print helpforculus audit-stream list
Section titled “forculus audit-stream list”List a workspace's audit log streams
Usage: forculus audit-stream list [OPTIONS] <WORKSPACE>
Arguments: <WORKSPACE> The workspace slug. For example, acme.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus audit-stream pause
Section titled “forculus audit-stream pause”Stop a stream for now. What happens meanwhile waits in the log.
Usage: forculus audit-stream pause [OPTIONS] <WORKSPACE> <ID>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The stream's id from `forculus audit-stream list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus audit-stream resume
Section titled “forculus audit-stream resume”Turn a stream back on. It sends what it missed, as far back as a week.
Usage: forculus audit-stream resume [OPTIONS] <WORKSPACE> <ID>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The stream's id from `forculus audit-stream list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus audit-stream test
Section titled “forculus audit-stream test”Send a test entry now and say how it went
Usage: forculus audit-stream test [OPTIONS] <WORKSPACE> <ID>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The stream's id from `forculus audit-stream list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus audit-stream failed
Section titled “forculus audit-stream failed”List the batches that failed for a day and wait to be sent again, kept for aweek
Usage: forculus audit-stream failed [OPTIONS] <WORKSPACE> <ID>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The stream's id from `forculus audit-stream list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus audit-stream retry
Section titled “forculus audit-stream retry”Send failed batches again: every one, or one with --batch. They go once thestream is on.
Usage: forculus audit-stream retry [OPTIONS] <WORKSPACE> <ID>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The stream's id from `forculus audit-stream list`
Options: --batch <BATCH> Only this batch, from `forculus audit-stream failed` --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus audit-stream remove
Section titled “forculus audit-stream remove”Remove a stream. Nothing more is sent to it, and what it hadn't sent goes withit.
Usage: forculus audit-stream remove [OPTIONS] <WORKSPACE> <ID>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The stream's id from `forculus audit-stream list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus log-drain
Section titled “forculus log-drain”Send apps' logs to a URL, Datadog, Grafana Loki or an S3 bucket as they'rewritten. A drain is for one app, added by whoever can share it, or for every appin a workspace, added by its owners. On Team, Business and Enterprise.
Usage: forculus log-drain [OPTIONS] <COMMAND>
Commands: add Start sending logs somewhere. Give one of --http, --datadog, --loki or --s3. The credential is asked for at the prompt or read from stdin, so it stays out of shell history: the Datadog API key, the Loki token, the secret access key, or with --header the header's value. list List log drains: every one in a workspace, or the ones that send one app's logs pause Stop a drain for now. Lines written while it's paused aren't sent. resume Turn a drain back on. It sends lines written from now on. level Change the quietest level a drain sends: debug, info, warn or error test Send a test line now and say how it went failed List the batches that failed for a day and wait to be sent again, kept for a week retry Send failed batches again: every one, or one with --batch. They go once the drain is on. remove Remove a drain. Nothing more is sent to it, and what it hadn't sent goes with it. help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus log-drain add
Section titled “forculus log-drain add”Start sending logs somewhere. Give one of --http, --datadog, --loki or --s3. Thecredential is asked for at the prompt or read from stdin, so it stays out ofshell history: the Datadog API key, the Loki token, the secret access key, orwith --header the header's value.
Usage: forculus log-drain add [OPTIONS] <TARGET>
Arguments: <TARGET> A workspace, for every app in it, or one app as <workspace>/<app>
Options: --http <URL> A URL that takes each batch as signed JSON lines. We show the signing secret once. --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --header <NAME> With --http: a header to send with each batch, like Authorization. Its value is asked for like a credential. --datadog <SITE> A Datadog site: datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com or ddog-gov.com --tags <TAGS> With --datadog: tags to add to every line, like env:prod,team:web --loki <URL> Grafana Loki: the host, like https://logs-prod-006.grafana.net, or the whole /loki/api/v1/push address --loki-user <USER> With --loki: the user to sign in as, like a Grafana Cloud user ID. Its token is asked for. --loki-token With --loki and no --loki-user: ask for a bearer token to send --tenant <TENANT> With --loki: the tenant, sent as X-Scope-OrgID --s3 <BUCKET> An S3 bucket: AWS's, R2's with --endpoint, or another that speaks S3 --region <REGION> With --s3: the bucket's region, like us-east-1, or auto for R2 --access-key-id <ACCESS_KEY_ID> With --s3: the access key ID. The secret access key is asked for. --endpoint <URL> With --s3: where the bucket is, if not AWS. For R2, https://<account id>.r2.cloudflarestorage.com. --prefix <PREFIX> With --s3: a folder to write under, like logs/payroll/ --level <LEVEL> The quietest level to send: debug (every line, the default), info, warn or error -h, --help Print helpforculus log-drain list
Section titled “forculus log-drain list”List log drains: every one in a workspace, or the ones that send one app's logs
Usage: forculus log-drain list [OPTIONS] <TARGET>
Arguments: <TARGET> A workspace, or one app as <workspace>/<app>
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus log-drain pause
Section titled “forculus log-drain pause”Stop a drain for now. Lines written while it's paused aren't sent.
Usage: forculus log-drain pause [OPTIONS] <WORKSPACE> <ID>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The drain's id from `forculus log-drain list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus log-drain resume
Section titled “forculus log-drain resume”Turn a drain back on. It sends lines written from now on.
Usage: forculus log-drain resume [OPTIONS] <WORKSPACE> <ID>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The drain's id from `forculus log-drain list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus log-drain level
Section titled “forculus log-drain level”Change the quietest level a drain sends: debug, info, warn or error
Usage: forculus log-drain level [OPTIONS] <WORKSPACE> <ID> <LEVEL>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The drain's id from `forculus log-drain list` <LEVEL> debug sends every line, and warn sends warnings and errors
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus log-drain test
Section titled “forculus log-drain test”Send a test line now and say how it went
Usage: forculus log-drain test [OPTIONS] <WORKSPACE> <ID>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The drain's id from `forculus log-drain list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus log-drain failed
Section titled “forculus log-drain failed”List the batches that failed for a day and wait to be sent again, kept for aweek
Usage: forculus log-drain failed [OPTIONS] <WORKSPACE> <ID>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The drain's id from `forculus log-drain list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus log-drain retry
Section titled “forculus log-drain retry”Send failed batches again: every one, or one with --batch. They go once thedrain is on.
Usage: forculus log-drain retry [OPTIONS] <WORKSPACE> <ID>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The drain's id from `forculus log-drain list`
Options: --batch <BATCH> Only this batch, from `forculus log-drain failed` --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus log-drain remove
Section titled “forculus log-drain remove”Remove a drain. Nothing more is sent to it, and what it hadn't sent goes withit.
Usage: forculus log-drain remove [OPTIONS] <WORKSPACE> <ID>
Arguments: <WORKSPACE> The workspace slug. For example, acme. <ID> The drain's id from `forculus log-drain list`
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus watch
Section titled “forculus watch”Follow requests and changes to a workspace or app as they happen
Usage: forculus watch [OPTIONS] <TARGET>
Arguments: <TARGET> A workspace, or one app as <workspace>/<app>
Options: --denies Only show refused requests --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --tail <TAIL> How many recent events to show before following [default: 20] --seconds <SECONDS> Stop after this many seconds instead of following until you stop it -h, --help Print helpforculus logs
Section titled “forculus logs”Show an app's output and exceptions, oldest first.
Works for container apps too. For the app's editors and owners, and theworkspace's owners and admins.
Usage: forculus logs [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: -f, --follow Keep printing new lines as they arrive, until you stop it
--json Print machine-readable JSON instead of text
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
--since <SINCE> How far back to start: 15m, 2h, 1d or an RFC 3339 time. Defaults to 1h. Your plan sets how far back logs go.
--level <LEVEL> Only lines at this level or higher: debug, info, log, warn or error. log is the same as info. Container output counts as info, stderr included, unless the app writes JSON lines with a level field.
--version <VERSION> Only lines written by this version
--search <SEARCH> Only lines containing this text. Not case-sensitive.
--limit <LIMIT> How many of the newest lines to show before following. At least 1 and at most 500.
[default: 100]
--seconds <SECONDS> With --follow, stop after this many seconds
--platform Also show our own lines about a container app's container, like starting and stopping it. They're marked "platform".
-h, --help Print help (see a summary with '-h')forculus top
Section titled “forculus top”Watch your apps, who has access and incoming requests in a live dashboard
Usage: forculus top [OPTIONS] [WORKSPACE]
Arguments: [WORKSPACE] The workspace to open. Defaults to your first one.
Options: --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus curl
Section titled “forculus curl”Send a request to an app through Forculus, as you or with a bypass token.
Like curl, it exits 0 whatever the app answers, a 404 or a 502 included. Add--fail to exit with code 22 on a 4xx or 5xx. It exits 1 when it couldn't sendthe request or the answer was cut off.
Usage: forculus curl [OPTIONS] <WORKSPACE/APP> [PATH]
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
[PATH] The path and query. For example, /api/items?page=2.
[default: /]
Options: --json Print machine-readable JSON instead of text
-X, --request <METHOD> The HTTP method. Defaults to GET, or POST when there's a body, like curl.
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
-d, --data <DATA> The request body
--data-stdin Read the request body from stdin, so it never shows in the process list
-H, --header <HEADERS> A request header as 'Name: value'. Repeat for more. Not Authorization: that carries your session or --token, and the app never gets it.
--token <TOKEN> Call with a bypass token instead of as yourself. The env var is safer, because flags end up in your shell history.
[env: FORCULUS_TOKEN]
--apps-url <URL> Where to send a bypass token. Defaults to the apps address `forculus login` saved, or https://forculuslabs-apps.tech, unless FORCULUS_API points at another platform. Without --token it has to be the saved address, because your session is never sent anywhere else.
[env: FORCULUS_APPS_URL]
--fail Exit with code 22 on a 4xx or 5xx, like curl --fail. Without it, any answer exits 0.
--preview <PREVIEW> Send the request to one of the app's previews instead of the live app: the preview's version, like 5, or its address. It goes as you, and only people the app is shared with get in.
-h, --help Print help (see a summary with '-h')forculus open
Section titled “forculus open”Print an app's URL
Usage: forculus open [OPTIONS] <WORKSPACE/APP>
Arguments: <WORKSPACE/APP> The app, as <workspace>/<app>. For example, acme/payroll.
Options: --json Print machine-readable JSON instead of text --preview <PREVIEW> Print the address of one of the app's previews instead: its version, like 5, while it's open. An address given here is checked to be one of the app's previews and printed back. --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. -h, --help Print helpforculus dev
Section titled “forculus dev”Run your app locally behind our sign-in edge, signed in as anyone you like
Usage: forculus dev [OPTIONS] [DIR] [-- <COMMAND>...]
Arguments: [DIR] The project to run [default: .] [COMMAND]... The command that starts your app. Defaults to what `forculus detect` finds.
Options: --as <WHO> Who to sign in as: owner, editor, viewer, agent, token, scheduler, webhook, outsider, nobody, or an email address. You can change it at http://127.0.0.1:<port>/.forculus while it runs. [default: owner] --json Print machine-readable JSON instead of text --config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus. --role <ROLE> The role of an email you sign in as (default owner), of the agent or of the token (default editor and viewer) [possible values: viewer, editor, owner] --provider <PROVIDER> Who signed a webhook, with --as webhook [possible values: stripe, github, slack, shopify, standard_webhooks, hmac_sha256] --pattern <PATTERN> The path that was opened for the webhook, with --as webhook: one path, /hooks/stripe, or everything under one, /hooks/* (the default). A delivery to any other path is refused, and the token names the pattern, as on the platform. --docker Run a container app in Docker, from the image a deploy would build, rather than with the tools on this machine. A project that's only a Dockerfile runs this way anyway. --port <PORT> The port to take requests on, the way Forculus would [default: 8787] --app-port <APP_PORT> The port your app listens on. We pass it to your app as PORT. [default: 8788] --app-id <APP_ID> The app id in each identity token. Your app checks it as the audience. [default: 00000000-0000-4000-8000-000000000000] -h, --help Print helpforculus mcp
Section titled “forculus mcp”Serve this CLI to an agent over MCP, as the person signed in here.
Your agent starts it and talks to it over stdio. For Cursor, run `forculus mcpinstall cursor` in your project. To add it to Claude Code or Codex, seehttps://forculuslabs.tech/docs/agents/.
Usage: forculus mcp [OPTIONS] [COMMAND]
Commands: install Add this server to an agent's settings for one project help Print this message or the help of the given subcommand(s)
Options: --json Print machine-readable JSON instead of text
--roots <DIR> The only directory deploys can read from
[env: FORCULUS_MCP_ROOTS]
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
-h, --help Print help (see a summary with '-h')forculus mcp install
Section titled “forculus mcp install”Add this server to an agent's settings for one project.
For Cursor it writes the project's .cursor/mcp.json with this forculus's fullpath, so Cursor finds it however Cursor was opened.
Usage: forculus mcp install [OPTIONS] <CLIENT>
Arguments: <CLIENT> The agent to add the server to
[possible values: cursor]
Options: --dir <DIR> The project to add it for. Deploys from the agent can read only inside it.
[default: .]
--json Print machine-readable JSON instead of text
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
-h, --help Print help (see a summary with '-h')forculus uninstall
Section titled “forculus uninstall”Remove the CLI from this computer: its session, its files and the program. Yourapps stay.
Ends this computer's session, revokes the bypass tokens your agent made here anddeletes their secret files, then deletes the config directory, keeping anythingin it we didn't put there. If the install script put forculus here, it deletesthe program and the lines the script added to your shell's startup files. ForHomebrew, npm, cargo and Windows it prints what to run. It takes forculus out ofthis project's .cursor/mcp.json, and says how to take it out of other agents.Your apps and workspaces aren't touched.
Usage: forculus uninstall [OPTIONS]
Options: --json Print machine-readable JSON instead of text
-y, --yes Don't ask before removing anything. Needed when there's no terminal to ask at.
--config-dir <CONFIG_DIR> Where your settings and session are kept. Defaults to $FORCULUS_CONFIG_DIR, then $XDG_CONFIG_HOME/forculus, then ~/.config/forculus. On Windows, %APPDATA%\forculus.
--keep-config Leave the config directory and your settings in it as they are
-h, --help Print help (see a summary with '-h')