CLI Reference

Complete reference for all FaraCore command-line interface commands.

Server Commands

faracore serve

Start the FaraCore server.

faracore serve

Options:

Server starts on http://127.0.0.1:8000 by default
Configure host/port via FARA_API_HOST and FARA_API_PORT

faracore migrate

Initialize or migrate the database schema.

faracore migrate

Creates tables and applies migrations. Works for both SQLite and PostgreSQL.

Action Commands

faracore list

List all actions.

faracore list

Displays actions in a table format with ID, agent, tool, operation, and status.

faracore get <action-id>

Get details of a specific action.

faracore get abc123

Shows full action details including parameters, decision, reason, and status.

faracore allow <action-id>

Approve an action.

faracore allow abc123

Approves a pending action. Requires the approval token if authentication is enabled.

faracore deny <action-id>

Deny an action.

faracore deny abc123

Denies a pending action. Requires the approval token if authentication is enabled.

Policy Commands

faracore policy-validate <file>

Validate a policy YAML file.

faracore policy-validate policies/default.yaml

Checks policy syntax and reports any errors. Exit code 0 if valid, 1 if invalid.

faracore policy-test <file>

Test how a policy evaluates a sample action.

# Create test-action.json
{
  "tool": "shell",
  "operation": "run",
  "params": {"cmd": "ls -la"},
  "context": {"agent_id": "test"}
}

# Test it
faracore policy-test test-action.json

Evaluates the action against the current policy and shows the decision, reason, and risk level.

faracore policy-refresh

Reload the policy file without restarting the server.

faracore policy-refresh

Reloads the policy from the configured file path (FARA_POLICY_FILE or default location).

Environment Variables

CLI commands respect these environment variables:

FARA_API_BASE - API base URL (default: http://127.0.0.1:8000)
FARA_AUTH_TOKEN - Bearer token for authentication
FARA_DB_BACKEND - Database backend: "sqlite" or "postgres"
FARA_POSTGRES_DSN - PostgreSQL connection string
FARA_SQLITE_PATH - SQLite database file path
FARA_POLICY_FILE - Policy file path

Examples

Start server and submit action

# Terminal 1: Start server
faracore serve

# Terminal 2: Submit action via API
curl -X POST http://127.0.0.1:8000/v1/actions \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"test","tool":"shell","operation":"run","params":{"cmd":"ls"}}'

# Terminal 2: List actions
faracore list

# Terminal 2: Approve action
faracore allow <action-id>

Validate and test policy

# Validate policy
faracore policy-validate policies/default.yaml

# Test policy with sample action
echo '{"tool":"shell","operation":"run","params":{"cmd":"ls"}}' > test.json
faracore policy-test test.json