CLI

The Faramesh CLI (faramesh) lets you manage actions, policies, and approvals from the terminal.

Setup

Point the CLI at your Faramesh instance and use your API key:

export FARAMESH_URL="https://api.faramesh.io"   # or http://localhost:8000
export FARAMESH_API_KEY="your-api-key"         # or FARAMESH_TOKEN for self-hosted

export FARAMESH_URL="https://api.faramesh.io"   # or http://localhost:8000
export FARAMESH_API_KEY="your-api-key"         # or FARAMESH_TOKEN for self-hosted

export FARAMESH_URL="https://api.faramesh.io"   # or http://localhost:8000
export FARAMESH_API_KEY="your-api-key"         # or FARAMESH_TOKEN for self-hosted

Common commands

Actions

faramesh list                           # List actions (filter by status, agent, tool)
faramesh get <action_id>                # Get action details
faramesh tail                           # Stream actions (live tail)
faramesh action approve <id> --token <approval_token>
faramesh action deny <id> --token

faramesh list                           # List actions (filter by status, agent, tool)
faramesh get <action_id>                # Get action details
faramesh tail                           # Stream actions (live tail)
faramesh action approve <id> --token <approval_token>
faramesh action deny <id> --token

faramesh list                           # List actions (filter by status, agent, tool)
faramesh get <action_id>                # Get action details
faramesh tail                           # Stream actions (live tail)
faramesh action approve <id> --token <approval_token>
faramesh action deny <id> --token

Policies

faramesh policy list                    # List policies
faramesh policy get <id>                # Get policy
faramesh policy create ...              # Create policy (from file or stdin)
faramesh policy update <id> ...         # Update policy
faramesh policy activate <id>           # Activate policy
faramesh policy validate                # Validate policy file locally
faramesh policy test                    # Run test cases against policy
faramesh policy diff                    # Diff local vs server policy
faramesh policy push                    # Push local YAML to server (import)

faramesh policy list                    # List policies
faramesh policy get <id>                # Get policy
faramesh policy create ...              # Create policy (from file or stdin)
faramesh policy update <id> ...         # Update policy
faramesh policy activate <id>           # Activate policy
faramesh policy validate                # Validate policy file locally
faramesh policy test                    # Run test cases against policy
faramesh policy diff                    # Diff local vs server policy
faramesh policy push                    # Push local YAML to server (import)

faramesh policy list                    # List policies
faramesh policy get <id>                # Get policy
faramesh policy create ...              # Create policy (from file or stdin)
faramesh policy update <id> ...         # Update policy
faramesh policy activate <id>           # Activate policy
faramesh policy validate                # Validate policy file locally
faramesh policy test                    # Run test cases against policy
faramesh policy diff                    # Diff local vs server policy
faramesh policy push                    # Push local YAML to server (import)

Tokens

faramesh token create                   # Create API token (self-hosted)
faramesh token list                     # List tokens
faramesh token revoke                   # Revoke token

faramesh token create                   # Create API token (self-hosted)
faramesh token list                     # List tokens
faramesh token revoke                   # Revoke token

faramesh token create                   # Create API token (self-hosted)
faramesh token list                     # List tokens
faramesh token revoke                   # Revoke token

Simple Policy (Allow/Ask/Deny)

faramesh policy show                   # Show current simple policy
faramesh policy show --agent-id my-bot # Show policy for a specific agent
faramesh policy set bash allow         # Set bash category to allow
faramesh policy set filesystem deny    # Set filesystem category to deny
faramesh policy set network ask        # Require approval for network calls

faramesh policy show                   # Show current simple policy
faramesh policy show --agent-id my-bot # Show policy for a specific agent
faramesh policy set bash allow         # Set bash category to allow
faramesh policy set filesystem deny    # Set filesystem category to deny
faramesh policy set network ask        # Require approval for network calls

faramesh policy show                   # Show current simple policy
faramesh policy show --agent-id my-bot # Show policy for a specific agent
faramesh policy set bash allow         # Set bash category to allow
faramesh policy set filesystem deny    # Set filesystem category to deny
faramesh policy set network ask        # Require approval for network calls

Agents & Runtimes

faramesh agents list                   # List all agents seen
faramesh runtimes list                 # List plugin runtimes (fleet)
faramesh status                        # Server health + policy + channels

faramesh agents list                   # List all agents seen
faramesh runtimes list                 # List plugin runtimes (fleet)
faramesh status                        # Server health + policy + channels

faramesh agents list                   # List all agents seen
faramesh runtimes list                 # List plugin runtimes (fleet)
faramesh status                        # Server health + policy + channels

OpenClaw Integration

faramesh openclaw install              # Install Faramesh plugin into OpenClaw
faramesh openclaw install --base-url http://127.0.0.1:8000
faramesh openclaw uninstall            # Remove Faramesh plugin
faramesh openclaw status               # Check plugin + server integration health

faramesh openclaw install              # Install Faramesh plugin into OpenClaw
faramesh openclaw install --base-url http://127.0.0.1:8000
faramesh openclaw uninstall            # Remove Faramesh plugin
faramesh openclaw status               # Check plugin + server integration health

faramesh openclaw install              # Install Faramesh plugin into OpenClaw
faramesh openclaw install --base-url http://127.0.0.1:8000
faramesh openclaw uninstall            # Remove Faramesh plugin
faramesh openclaw status               # Check plugin + server integration health

For full OpenClaw integration documentation, see the OpenClaw Integration Guide.

Server (self-hosted only)

faramesh serve                          # Start the API server
faramesh status                         # Server health, policy, channels
faramesh migrate --from sqlite --to postgres  # Migrate database

faramesh serve                          # Start the API server
faramesh status                         # Server health, policy, channels
faramesh migrate --from sqlite --to postgres  # Migrate database

faramesh serve                          # Start the API server
faramesh status                         # Server health, policy, channels
faramesh migrate --from sqlite --to postgres  # Migrate database

Diagnostics

faramesh doctor                         # Check config, connectivity, and common issues
faramesh status                         # Full health check (server, policy, notification channels)

faramesh doctor                         # Check config, connectivity, and common issues
faramesh status                         # Full health check (server, policy, notification channels)

faramesh doctor                         # Check config, connectivity, and common issues
faramesh status                         # Full health check (server, policy, notification channels)

Environment variables

Variable	Description
`FARAMESH_URL`	API base URL (e.g. `https://api.faramesh.io` or `http://localhost:8000`)
`FARAMESH_API_KEY`	API key (Horizon); used for authenticated requests
`FARAMESH_TOKEN`	Auth token (self-hosted); alternative to API key

All policy and action commands use these. Override per-command with --host, --port, or --token when needed.

Flags

--json — Output as JSON
--token — Override auth token for a single command
--host / --port — Override server address

Table of content