Flocks CLI

This page summarizes Flocks terminal CLI commands for local operations scenarios such as service start and stop, log viewing, task management, MCP management, Skill installation, account maintenance, and session import and export.

Slash commands in the session input box are documented separately in Flocks Slash Commands.

1. Entry Points

1.1 Terminal CLI

The Flocks command-line entry point is:

flocks <command>

Common help commands:

flocks --help
flocks <command> --help
flocks <command> <subcommand> --help

The CLI is suitable for local operations scenarios such as service start and stop, log viewing, task management, MCP management, Skill installation, account maintenance, and session import and export.

2. Top-Level CLI Commands

2.1 Command Group Overview

Command Group	Purpose
flocks start/stop/restart/status/logs	Service start and stop, status, and logs.
flocks tui	Start the TUI session interface in the terminal.
flocks browser	Invoke the built-in browser runtime.
flocks session ...	Session list, details, deletion, archive, and restore.
flocks task ...	Task Center, queue, scheduled tasks, and task reruns.
flocks mcp ...	MCP Server and MCP tool management.
flocks skills ...	Skill query, installation, removal, and dependency installation.
flocks admin ...	Local account, security Token, historical session, and Workspace maintenance.
flocks export	Export session JSON.
flocks import	Import session JSON or a shared link.
flocks stats	Usage, cost, and historical record backfill.
flocks update	Update Flocks.

2.2 Service and Interaction Commands

Command	Purpose	Common Example
flocks start	Start the backend and WebUI as daemons.	flocks start --no-browser
flocks stop	Stop the backend and WebUI.	flocks stop
flocks restart	Restart the backend and WebUI.	flocks restart --port 5173
flocks status	View backend and WebUI status.	flocks status
flocks logs	View backend and WebUI logs.	flocks logs --backend -n 100
flocks tui	Start the TUI session interface.	flocks tui --directory .
flocks browser	Pass through to the built-in browser runtime.	flocks browser --help
flocks update	Run version update.	flocks update
flocks serve	Start Flocks API Server directly. Hidden command, mainly used for development and debugging.	flocks serve --host 127.0.0.1 --port 8000

Common options:

• flocks start/restart --no-browser: do not open the browser automatically after startup.
• flocks start/restart --skip-webui-build: skip WebUI build.
• flocks start/restart --host <host> --port <port>: specify the public service address shared by WebUI and API.
• flocks start/restart --server-host/--server-port and --webui-host/--webui-port: advanced options compatible with older startup configuration. For normal deployments, prefer --host/--port.
• If flocks restart is executed without specifying an address and port, it attempts to reuse the existing service configuration.
• flocks logs --backend: show only backend logs.
• flocks logs --webui: show only WebUI logs.
• flocks logs --follow/--no-follow: whether to follow logs continuously.
• flocks tui --session <session_id>: continue a specified session.
• flocks tui --auto-approve/--no-auto-approve: control whether tool calls are automatically approved in TUI.

flocks run is a session entry point in the TUI / Node CLI source code. It is not a stable command registered in the current Python flocks main CLI. When using the Python package or npm wrapper, rely on the output of flocks --help; usually use flocks tui to enter a terminal session.

3. Session CLI

Command	Purpose
flocks session list	List sessions.
flocks session show <session_id>	View session details.
flocks session delete <session_id>	Delete a session. Confirmation is required by default.
flocks session archive <session_id>	Archive a session.
flocks session restore <session_id>	Restore an archived session.

Common examples:

flocks session list -n 20
flocks session list --format json
flocks session list --project ""
flocks session show <session_id>
flocks session delete <session_id> --force

Here, --project "" means filtering sessions in the current project.

4. Task Center CLI

Command	Purpose
flocks task	Show the Task Center overview by default.
flocks task dashboard	Show the Task Center overview.
flocks task list	List task executions or schedules.
flocks task show <taskID>	View task details.
flocks task create <title>	Create a task.
flocks task queue	View or control the task queue.
flocks task scheduled	List scheduled tasks.
flocks task cancel <taskID>	Cancel a task.
flocks task retry <taskID>	Retry a failed task.
flocks task rerun <taskID>	Rerun a task.

Common examples:

flocks task list --status running
flocks task list --type scheduled --format json
flocks task create "Daily inspection" --type scheduled --cron "0 8 * * *" --prompt "Run device inspection and send a summary"
flocks task create "Alert triage" --mode workflow --workflow ndr-alert-triage --prompt "Process this batch of alerts"
flocks task queue --pause
flocks task queue --resume

Common task creation parameters:

• --type queued|scheduled|stream: task type.
• --priority urgent|high|normal|low: priority.
• --mode agent|workflow: execution mode.
• --agent <name>: Agent used in Agent mode.
• --workflow <id>: Workflow used in Workflow mode.
• --skill <name>: inject a Skill. Can be used repeatedly.
• --cron "<expr>": Cron expression for scheduled tasks.
• --prompt "<text>": task execution prompt.

5. MCP CLI

Command	Purpose
flocks mcp list	List MCP Server and status.
flocks mcp add	Add MCP Server. Enters interactive mode if no arguments are provided.
flocks mcp auth [name]	Run the authentication flow for an OAuth MCP Server.
flocks mcp logout [name]	Delete MCP OAuth credentials.
flocks mcp debug <name>	Debug MCP OAuth status.
flocks mcp connect <name>	Connect MCP Server.
flocks mcp disconnect <name>	Disconnect MCP Server.
flocks mcp tools [server]	List MCP tools.
flocks mcp refresh [server]	Refresh MCP tools.

Common examples:

flocks mcp list
flocks mcp list --format json
flocks mcp add --name github --type remote --url https://example.com/mcp
flocks mcp add --name local-tools --type local --command "uvx my-mcp-server"
flocks mcp tools
flocks mcp refresh github

6. Skills CLI

Command	Purpose
flocks skills list	List discovered Skills.
flocks skills status	Check Skill dependency status.
flocks skills find <query>	Search installable Skills.
flocks skills install <source>	Install a Skill.
flocks skills remove <name>	Remove a user-installed Skill.
flocks skills install-deps <name>	Install dependencies declared by a Skill.

Common examples:

flocks skills list --status
flocks skills list --json
flocks skills find "threat intel"
flocks skills install clawhub:github
flocks skills install skills-sh:owner/repo/skill-name
flocks skills install safeskill://...
flocks skills install github:owner/repo --skill skill-name
flocks skills install https://example.com/SKILL.md
flocks skills install /local/path/to/skill
flocks skills remove skill-name --yes
flocks skills install-deps skill-name

Skill installation supports global and project scopes:

flocks skills install github:owner/repo/skills/foo --scope project

project installs to .flocks/plugins/skills/ under the current project directory and does not write to the Workspace business file directory. flocks skills remove can only delete user-level Skills under ~/.flocks/plugins/skills/.

7. Account and Security CLI

Command	Purpose
flocks admin list-users	List local accounts.
flocks admin generate-one-time-password --username admin	Generate a one-time temporary password for an administrator.
flocks admin generate-api-token	Generate and save an API Token.
flocks admin set-api-token --token <token>	Write the specified API Token.
flocks admin reassign-orphan-sessions --username admin	Assign unowned historical sessions to the specified administrator.
flocks admin migrate-workspace-to-user --admin-user-id <user_id>	Migrate the historical single-user Workspace to the multi-account layout.

Common examples:

flocks admin list-users
flocks admin generate-one-time-password --username admin
flocks admin generate-api-token
flocks admin reassign-orphan-sessions --username admin --dry-run
flocks admin migrate-workspace-to-user --admin-user-id <user_id> --dry-run

8. Import, Export, and Statistics CLI

8.1 Export Sessions

flocks export <session_id>
flocks export <session_id> -o session.json
flocks export <session_id> --no-pretty

If session_id is not provided, the CLI lists recent sessions and asks you to choose one.

8.2 Import Sessions

flocks import session.json
flocks import session.json --project <projectID>
flocks import https://opncd.ai/share/<slug>
flocks import https://flocks.ai/share/<slug>

Import supports local JSON files and Flocks shared links.

8.3 Usage Statistics

flocks stats
flocks stats --days 7
flocks stats --tools 0
flocks stats --models 10
flocks stats --project ""
flocks stats backfill --days 30

flocks stats is used to view Token, model, tool, and cost statistics. backfill is used to backfill usage records from historical message metadata.

9. Commands Visible in Source Code but Not Registered in the Current Main Entry Point

The source code also contains Typer command definitions such as agent, debug, debug snapshot, and acp, but the current flocks main CLI registry does not attach these commands to the main entry point. Check actual availability with the output of flocks --help.

These commands involve:

• agent list/show/permissions: view Agent and permissions.
• debug info/config: view debugging information and configuration.
• debug snapshot track/patch/diff/restore/cleanup: debug Snapshot.
• acp: Agent Client Protocol capabilities.

Related features may already have entry points in the WebUI, TUI, or internal debugging paths. For ordinary daily use, prefer the stable CLI commands listed earlier on this page. For in-session shortcuts, see Flocks Slash Commands.

10. Related Modules

• Flocks Slash Commands: / commands in WebUI, TUI, IM, and CLI sessions.
• Task Center: task CLI corresponds to task page capabilities.
• Tool Inventory: /tools, /mcp, and MCP CLI correspond to this page.
• Skills: Skills CLI corresponds to Skill page capabilities.
• Account Management: administrator password recovery and account CLI.