Skip to main content

​
The foks binary

The foks binary is the main CLI for FOKS. When invoked as git-remote-foks (a symlink), it acts as a Git remote helper. Most subcommands require the FOKS agent to be running (foks ctl start).

​
Global flags

FlagDescription
--jsonOutput in JSON format
--config <path>Path to config file (default: ~/.config/foks/config.json)
--home <path>FOKS home directory override

​
Top-level commands

CommandDescription
foks signupSign up for a new account
foks ctlControl the background agent
foks agentRun the agent directly
foks gitManage encrypted Git repositories
foks kvKey-value store
foks teamTeam management
foks deviceDevice provisioning and management
foks yubikeyYubiKey management
foks passphrasePassphrase management
foks ssoSSO / OAuth2 login
foks adminAdmin operations (web panel login)
foks statusShow agent and account status
foks pingPing the agent
foks versionPrint version information

​
signup

foks signup
Interactive signup flow. Prompts for a server (default: foks.app), username, and invite code. Creates a new device key and registers it with the server. On servers configured with OAuth2 SSO, signup can be restricted to members of your organization and FOKS usernames are matched to your identity provider’s naming scheme. Your resulting identity is a user@host pair, e.g. alice@foks.app.

​
passphrase

foks passphrase set       # set a passphrase for the first time
foks passphrase change    # change an existing passphrase
foks passphrase unlock    # unlock credentials with a passphrase
Passphrases protect device keys at rest. They are stored only on the local machine; the server never sees them.

​
sso

foks sso login
Re-authenticate with the identity provider (IdP) on a server that has OAuth2 SSO enabled. Prints a URL to open in your browser to complete the OAuth2 flow. Useful when your session has been invalidated — for example, after the server admin reconfigures SSO or your IDP token has expired beyond the refresh window.

​
admin

foks admin web            # open (or print) a login URL for the web admin panel
foks admin check-link     # verify a login link is still valid

​
status

foks status
Shows the current agent state, logged-in user, pending key rotations, and connectivity to the server.

​
ping

foks ping
Pings the local agent to confirm it is running and responsive.