# Command reference

Every faros command with its flags and examples, generated from the CLI.

Source: https://faros.sh/docs/reference/cli/commands/

<!-- Generated by scripts/sync-cli-docs.py from faroshq/faros docs/cli. Do not edit by hand; run `make sync-cli-docs`. -->

## Synopsis

faros connects Kubernetes clusters and Linux servers behind NAT to one
hub, and gives every team an isolated workspace with its own APIs, RBAC and
providers on top.

Typical session:

```bash
faros login --hub-url https://hub.example.com   # OIDC in the browser
faros use                                        # pick an org and workspace
faros edge list                                  # what is connected
faros connect my-cluster                         # point kubectl at an edge
faros ssh my-server                              # shell on a Linux edge
faros whoami                                     # where am I, what can I do
```

Every command talks to the hub as you, with your workspace RBAC. Run
'faros \<command> --help' for details and 'faros completion --help' for shell
completion.

## Options

```text
  -h, --help                       help for faros
      --insecure-skip-tls-verify   Skip TLS certificate verification when talking to the hub
      --kubeconfig string          Path to the kubeconfig file (default: $KUBECONFIG, then ~/.kube/config)
```

## See also

- [faros agent](https://faros.sh/docs/reference/cli/commands/agent/) — Run, install or upgrade the edge agent on a cluster or server
- [faros app](https://faros.sh/docs/reference/cli/commands/app/) — Manage App Studio projects: list, create, status, sync, promote, publish
- [faros commit](https://faros.sh/docs/reference/cli/commands/commit/) — Record local git commits through faros (code__commit_files)
- [faros completion](https://faros.sh/docs/reference/cli/commands/completion/) — Generate the autocompletion script for the specified shell
- [faros connect](https://faros.sh/docs/reference/cli/commands/connect/) — Point kubectl at a Kubernetes edge
- [faros dev](https://faros.sh/docs/reference/cli/commands/dev/) — Manage development environment for faros
- [faros disconnect](https://faros.sh/docs/reference/cli/commands/disconnect/) — Point kubectl back at the hub workspace
- [faros edge](https://faros.sh/docs/reference/cli/commands/edge/) — Create, list, inspect and remove edges (clusters and servers)
- [faros env](https://faros.sh/docs/reference/cli/commands/env/) — Print shell exports for calling the hub as you
- [faros init](https://faros.sh/docs/reference/cli/commands/init/) — Run a faros hub in-process (server side, not a client command)
- [faros install](https://faros.sh/docs/reference/cli/commands/install/) — Install the faros agent
- [faros login](https://faros.sh/docs/reference/cli/commands/login/) — Log in to a faros hub (browser OIDC flow, or a static token)
- [faros logout](https://faros.sh/docs/reference/cli/commands/logout/) — Forget the hub credentials on this machine
- [faros mcp](https://faros.sh/docs/reference/cli/commands/mcp/) — MCP endpoints for AI clients (Claude Code, Cursor, Codex)
- [faros org](https://faros.sh/docs/reference/cli/commands/org/) — Organizations you belong to, and who is in them
- [faros sandbox](https://faros.sh/docs/reference/cli/commands/sandbox/) — Drive a development-mode instance: sync, exec, logs, restart, status
- [faros skills](https://faros.sh/docs/reference/cli/commands/skills/) — Install agent skills from the faros repository into Claude Code and Codex
- [faros ssh](https://faros.sh/docs/reference/cli/commands/ssh/) — Open an SSH session to a Linux server edge via the hub
- [faros token](https://faros.sh/docs/reference/cli/commands/token/) — Print a bearer token for the hub (refreshing it when needed)
- [faros use](https://faros.sh/docs/reference/cli/commands/use/) — Switch the active organization and workspace
- [faros version](https://faros.sh/docs/reference/cli/commands/version/) — Print version information
- [faros whoami](https://faros.sh/docs/reference/cli/commands/whoami/) — Show who you are logged in as, and where kubectl points
- [faros workspace](https://faros.sh/docs/reference/cli/commands/workspace/) — Workspaces of an organization, and who is in them


## In this section

- [faros agent](https://faros.sh/docs/reference/cli/commands/agent/): Run, install or upgrade the edge agent on a cluster or server
- [faros agent install](https://faros.sh/docs/reference/cli/commands/agent-install/): Install faros agent as a systemd or launchd service
- [faros agent join](https://faros.sh/docs/reference/cli/commands/agent-join/): Persistently join an edge to the hub (installs systemd, launchd, or Kubernetes deployment)
- [faros agent run](https://faros.sh/docs/reference/cli/commands/agent-run/): Run the agent as a foreground process (for containers/dev; use 'join' for persistent install)
- [faros agent token](https://faros.sh/docs/reference/cli/commands/agent-token/): Manage agent tokens
- [faros agent token create](https://faros.sh/docs/reference/cli/commands/agent-token-create/): Create a bootstrap token for an edge
- [faros agent uninstall](https://faros.sh/docs/reference/cli/commands/agent-uninstall/): Uninstall faros agent systemd or launchd service
- [faros agent upgrade](https://faros.sh/docs/reference/cli/commands/agent-upgrade/): Upgrade the agent for an edge deployed via 'faros agent join'
- [faros app](https://faros.sh/docs/reference/cli/commands/app/): Manage App Studio projects: list, create, status, sync, promote, publish
- [faros app create](https://faros.sh/docs/reference/cli/commands/app-create/): Create a project (repository, scaffold commit and dev instance)
- [faros app list](https://faros.sh/docs/reference/cli/commands/app-list/): List App Studio projects
- [faros app promote](https://faros.sh/docs/reference/cli/commands/app-promote/): Promote the latest built commit (or --commit) to production
- [faros app publish](https://faros.sh/docs/reference/cli/commands/app-publish/): Set production visibility: public, restricted or private
- [faros app status](https://faros.sh/docs/reference/cli/commands/app-status/): Show a project's repository, commits, promotion and publishing state
- [faros app sync](https://faros.sh/docs/reference/cli/commands/app-sync/): Load the repository into the project workspace and sync it to <name>-dev
- [faros commit](https://faros.sh/docs/reference/cli/commands/commit/): Record local git commits through faros (code__commit_files)
- [faros completion](https://faros.sh/docs/reference/cli/commands/completion/): Generate the autocompletion script for the specified shell
- [faros completion bash](https://faros.sh/docs/reference/cli/commands/completion-bash/): Generate the autocompletion script for bash
- [faros completion fish](https://faros.sh/docs/reference/cli/commands/completion-fish/): Generate the autocompletion script for fish
- [faros completion powershell](https://faros.sh/docs/reference/cli/commands/completion-powershell/): Generate the autocompletion script for powershell
- [faros completion zsh](https://faros.sh/docs/reference/cli/commands/completion-zsh/): Generate the autocompletion script for zsh
- [faros connect](https://faros.sh/docs/reference/cli/commands/connect/): Point kubectl at a Kubernetes edge
- [faros dev](https://faros.sh/docs/reference/cli/commands/dev/): Manage development environment for faros
- [faros dev delete](https://faros.sh/docs/reference/cli/commands/dev-delete/): Delete development environment
- [faros dev init](https://faros.sh/docs/reference/cli/commands/dev-init/): Initialize a local faros environment (hub kind cluster + optional workers)
- [faros dev update](https://faros.sh/docs/reference/cli/commands/dev-update/): Upgrade the faros-hub release on an existing local environment
- [faros disconnect](https://faros.sh/docs/reference/cli/commands/disconnect/): Point kubectl back at the hub workspace
- [faros edge](https://faros.sh/docs/reference/cli/commands/edge/): Create, list, inspect and remove edges (clusters and servers)
- [faros edge create](https://faros.sh/docs/reference/cli/commands/edge-create/): Create an edge and print its join command
- [faros edge delete](https://faros.sh/docs/reference/cli/commands/edge-delete/): Delete an edge (the agent on it loses hub access)
- [faros edge get](https://faros.sh/docs/reference/cli/commands/edge-get/): Show an edge's connection status and details
- [faros edge join-command](https://faros.sh/docs/reference/cli/commands/edge-join-command/): Print the agent join command for an edge
- [faros edge kubeconfig](https://faros.sh/docs/reference/cli/commands/edge-kubeconfig/): Print or merge a kubeconfig for a Kubernetes edge
- [faros edge list](https://faros.sh/docs/reference/cli/commands/edge-list/): List edges
- [faros edge upgrade](https://faros.sh/docs/reference/cli/commands/edge-upgrade/): Print upgrade instructions for an edge agent
- [faros env](https://faros.sh/docs/reference/cli/commands/env/): Print shell exports for calling the hub as you
- [faros init](https://faros.sh/docs/reference/cli/commands/init/): Run a faros hub in-process (server side, not a client command)
- [faros install](https://faros.sh/docs/reference/cli/commands/install/): Install the faros agent
- [faros login](https://faros.sh/docs/reference/cli/commands/login/): Log in to a faros hub (browser OIDC flow, or a static token)
- [faros logout](https://faros.sh/docs/reference/cli/commands/logout/): Forget the hub credentials on this machine
- [faros mcp](https://faros.sh/docs/reference/cli/commands/mcp/): MCP endpoints for AI clients (Claude Code, Cursor, Codex)
- [faros mcp url](https://faros.sh/docs/reference/cli/commands/mcp-url/): Print the MCP endpoint URL
- [faros org](https://faros.sh/docs/reference/cli/commands/org/): Organizations you belong to, and who is in them
- [faros org create](https://faros.sh/docs/reference/cli/commands/org-create/): Create an organization (you become its admin)
- [faros org list](https://faros.sh/docs/reference/cli/commands/org-list/): List the organizations you belong to
- [faros org members](https://faros.sh/docs/reference/cli/commands/org-members/): List and change who has access to the organization
- [faros org members add](https://faros.sh/docs/reference/cli/commands/org-members-add/): Add a member to the organization (admin only)
- [faros org members list](https://faros.sh/docs/reference/cli/commands/org-members-list/): List organization members
- [faros org members remove](https://faros.sh/docs/reference/cli/commands/org-members-remove/): Remove a member from the organization (admin only)
- [faros org members set-role](https://faros.sh/docs/reference/cli/commands/org-members-set-role/): Change a member's role in the organization (admin only)
- [faros sandbox](https://faros.sh/docs/reference/cli/commands/sandbox/): Drive a development-mode instance: sync, exec, logs, restart, status
- [faros sandbox env](https://faros.sh/docs/reference/cli/commands/sandbox-env/): Set environment variables on the component's running dev process
- [faros sandbox exec](https://faros.sh/docs/reference/cli/commands/sandbox-exec/): Run a command in the component and exit with its exit code
- [faros sandbox logs](https://faros.sh/docs/reference/cli/commands/sandbox-logs/): Print the dev process log
- [faros sandbox restart](https://faros.sh/docs/reference/cli/commands/sandbox-restart/): Restart the component's dev process
- [faros sandbox status](https://faros.sh/docs/reference/cli/commands/sandbox-status/): Show the instance status, or a component's process state
- [faros sandbox sync](https://faros.sh/docs/reference/cli/commands/sandbox-sync/): Push a directory into the component workspace (authoritative)
- [faros skills](https://faros.sh/docs/reference/cli/commands/skills/): Install agent skills from the faros repository into Claude Code and Codex
- [faros skills install](https://faros.sh/docs/reference/cli/commands/skills-install/): Install skills for Claude Code and Codex (all skills by default)
- [faros skills list](https://faros.sh/docs/reference/cli/commands/skills-list/): List the skills available in the repository
- [faros ssh](https://faros.sh/docs/reference/cli/commands/ssh/): Open an SSH session to a Linux server edge via the hub
- [faros token](https://faros.sh/docs/reference/cli/commands/token/): Print a bearer token for the hub (refreshing it when needed)
- [faros use](https://faros.sh/docs/reference/cli/commands/use/): Switch the active organization and workspace
- [faros version](https://faros.sh/docs/reference/cli/commands/version/): Print version information
- [faros whoami](https://faros.sh/docs/reference/cli/commands/whoami/): Show who you are logged in as, and where kubectl points
- [faros workspace](https://faros.sh/docs/reference/cli/commands/workspace/): Workspaces of an organization, and who is in them
- [faros workspace create](https://faros.sh/docs/reference/cli/commands/workspace-create/): Create a workspace in an organization
- [faros workspace list](https://faros.sh/docs/reference/cli/commands/workspace-list/): List the workspaces of an organization
- [faros workspace members](https://faros.sh/docs/reference/cli/commands/workspace-members/): List and change who has access to the workspace
- [faros workspace members add](https://faros.sh/docs/reference/cli/commands/workspace-members-add/): Add a member to the workspace (admin only)
- [faros workspace members list](https://faros.sh/docs/reference/cli/commands/workspace-members-list/): List workspace members
- [faros workspace members remove](https://faros.sh/docs/reference/cli/commands/workspace-members-remove/): Remove a member from the workspace (admin only)
- [faros workspace members set-role](https://faros.sh/docs/reference/cli/commands/workspace-members-set-role/): Change a member's role in the workspace (admin only)