CLI Reference

Everything filcaas can do. Click the copy icon on any code block to grab the command.

Quick start

Four commands to get from zero to a synced workspace.

1. Install the CLI (macOS/Linux)

$curl -fsSL https://filcaas.com/install.sh | bash

1b. Install (Windows)

$iwr -useb https://filcaas.com/install.ps1 | iex

2. Authenticate, initialize, and start syncing

$filcaas start

Common workflows

Three scenarios you'll hit often.

First time on a project

Run from any project folder. The CLI detects your existing agent files (or asks one question if there are none), creates a cloud workspace, and uploads everything.

$cd ~/path/to/your/project

$filcaas start

Day-to-day editing

Edit your config files locally or via the dashboard. Since the daemon is running in the background (installed via filcaas start), changes are synced automatically. You only need to run sync manually if you disabled the daemon.

# edit CLAUDE.md (or whatever your tool uses)

# changes are synced automatically

Setting up a second machine

Install the CLI, start it, and pull the workspace into a new folder.

$filcaas start

$filcaas init --from my-startup

Commands

filcaasstart

One-command setup: login, init, and start syncing.

The fastest way to get started. This command opens your browser to authenticate, initializes the current folder as a workspace, performs the initial sync, and installs/starts the background daemon so that changes sync automatically.

Syntax

$filcaas start

Examples

# Setup current folder

$filcaas start

filcaasdaemon

Manage the background sync daemon.

Commands to install, uninstall, start, or stop the background service that watches for file changes and syncs them automatically. 'filcaas start' calls 'daemon install' under the hood.

Syntax

$filcaas daemon <install|uninstall|start|stop>

Options

Parameter	Type / Default	Description
install	subcommandDefault: —	Install and start the background daemon.
uninstall	subcommandDefault: —	Stop and remove the background daemon.
start	subcommandDefault: —	Start the installed daemon.
stop	subcommandDefault: —	Stop the running daemon.

Examples

# Install background sync

$filcaas daemon install

# Stop background sync temporarily

$filcaas daemon stop

filcaaslogin

Save an API token to this machine.

Saves your token so subsequent commands can authenticate. Generate a token from the dashboard's Tokens page.

Syntax

$filcaas login --token <api_token>

Options

Parameter	Type / Default	Description
--token, -t	stringDefault: required	API token from the dashboard.

Examples

# Save a token

$filcaas login --token agt_xxxxxxxx

filcaasinit

Create a workspace in the current folder (or clone one from the cloud).

Detects existing agent config files (CLAUDE.md, .cursorrules, .claude/, etc.) and imports them. If none are detected, asks which AI tool you use, scans your repo, and generates a single config file using a template from the cloud. Auto-pushes to the cloud at the end. Use --from to pull down a workspace that already lives in the cloud.

Syntax

$filcaas init [--name <name>] [--from <name>] [--no-push] [--no-hide-ide]

Options

Parameter	Type / Default	Description
--name, -n	stringDefault: current folder name	Workspace name to use when creating a new workspace. Skips the interactive picker.
--from	stringDefault: —	Clone an existing cloud workspace by name into a new subfolder.
--directory, -d	PathDefault: ./<name>	Target folder for --from. Must be empty or non-existent.
--no-push	booleanDefault: false	Skip the automatic cloud upload at the end of init. Run 'filcaas up' yourself later.
--no-hide-ide	booleanDefault: false	Skip auto-hiding the local sync folder from VS Code / Cursor / Zed / Sublime / JetBrains explorers.
--force, -f	booleanDefault: false	Overwrite the target file in generate-mode if it already exists.

Examples

# First run in a new folder

$filcaas init

# Pull a workspace onto a second machine

$filcaas init --from my-startup

# Initialize without auto-pushing

$filcaas init --no-push

filcaassync

Bidirectional sync with the cloud.

Uploads your local changes and downloads cloud changes in one pass. If the same file changed on both sides, sync prompts per file with [L] Keep local / [C] Keep cloud / [M] Merge so you decide each outcome. Prefer silent newest-wins? Pass --auto for one run, or save 'filcaas config set conflict.strategy auto' as your default. The losing version is always preserved as a backup.

Syntax

$filcaas sync [workspace_path] [--interactive | --auto]

Options

Parameter	Type / Default	Description
workspace_path	PathDefault: current directory	The folder to sync. Defaults to your cwd.
--interactive / --auto, -i	booleanDefault: prompt (interactive)	Force the [L]/[C]/[M] prompt for one run (--interactive) or force silent newest-wins (--auto). If neither flag is given, the CLI uses your saved conflict.strategy preference, which defaults to interactive.

Examples

# Sync the current folder

$filcaas sync

# Force prompts for this run

$filcaas sync --interactive

# Force silent newest-wins for this run

$filcaas sync --auto

filcaasstatus

Preview what sync would do.

Shows what's pending: uploads, downloads, and conflicts. Nothing is written. Use it before a sync when you're unsure of the state.

Syntax

$filcaas status [workspace_path]

Options

Parameter	Type / Default	Description
workspace_path	PathDefault: current directory	The folder to check.

Examples

# Check current folder

$filcaas status

filcaasresolve

Redo a past conflict outcome for one file.

If sync auto-resolved a conflict the wrong way (because you passed --auto, set conflict.strategy auto, or ran sync in a non-TTY like CI), run resolve on that file. The CLI loads the backed-up version, shows the [L] Keep local / [C] Keep cloud / [B] Keep both / [M] Merge prompt, applies your choice, and pushes the result.

Syntax

$filcaas resolve <path>

Options

Parameter	Type / Default	Description
path	stringDefault: required	Relative path of the file to re-decide (e.g. CLAUDE.md).

Examples

# Flip a CLAUDE.md decision

$filcaas resolve CLAUDE.md

filcaaslist

Show your cloud workspaces.

Lists every workspace owned by the authenticated account, with last-sync time and short id.

Syntax

$filcaas list

Examples

# List all workspaces

$filcaas list

filcaaslink

Bind or unbind a folder to a cloud workspace.

Binds this folder to the named cloud workspace. Use --remove to clear the binding without affecting the cloud workspace itself.

Syntax

$filcaas link <name> | filcaas link --remove

Options

Parameter	Type / Default	Description
name	stringDefault: —	Workspace name to bind this folder to.
--remove	booleanDefault: false	Remove the local binding. Cloud workspace is preserved.

Examples

# Bind current folder

$filcaas link my-startup

# Unlink (cloud workspace stays)

$filcaas link --remove

filcaasdelete

Delete a cloud workspace and its files.

Deletes the workspace and its files from the cloud. If the folder you're standing in is bound to the workspace you're deleting, the local binding is also removed.

Syntax

$filcaas delete <name> [--force]

Options

Parameter	Type / Default	Description
name	stringDefault: required	Workspace name to delete.
--force, -f	booleanDefault: false	Skip the confirmation prompt.

Examples

# Delete with confirmation

$filcaas delete my-old-workspace

# Delete without prompt (scripts)

$filcaas delete my-old-workspace --force

filcaasconfig

Read or write user preferences.

Currently the only validated key is conflict.strategy. Set it to 'auto' to make sync silently pick the newer side, or 'interactive' to get the [L]/[C]/[M] prompt every time. Leaving it unset keeps the interactive default.

Syntax

$filcaas config get <key> | filcaas config set <key> <value> | filcaas config unset <key> | filcaas config list

Options

Parameter	Type / Default	Description
<key>	stringDefault: —	Preference key (currently only conflict.strategy).
<value>	stringDefault: —	Allowed values for conflict.strategy: auto \| interactive.

Examples

# Always auto-resolve conflicts (no prompt)

$filcaas config set conflict.strategy auto

# Always prompt per conflict

$filcaas config set conflict.strategy interactive

# Back to default (prompt per conflict)

$filcaas config unset conflict.strategy

# Show all preferences

$filcaas config list

filcaasconvert

Translate between AI tool config formats.

Converts a single source format (e.g. .cursorrules) into other tools (e.g. CLAUDE.md, .windsurfrules), or use --reconcile to re-derive every detected format from the source of truth (AGENTS.md by default).

Syntax

$filcaas convert --from <format> [--to <format>] [--dry-run] | filcaas convert --reconcile

Options

Parameter	Type / Default	Description
--from	agents \| claude \| cursor \| windsurf \| copilotDefault: —	Source format to convert from. Required unless --reconcile is set.
--to	stringDefault: all formats	Target format. Defaults to deriving every supported format.
--reconcile	booleanDefault: false	Auto-detect the source and re-derive every other detected format.
--dry-run	booleanDefault: false	Preview the result without writing files.

Examples

# Convert Cursor rules to every other format

$filcaas convert --from cursor

# Just Claude to Cursor

$filcaas convert --from claude --to cursor

# Preview without writing

$filcaas convert --from cursor --dry-run

# Re-derive every detected format from AGENTS.md

$filcaas convert --reconcile

filcaasup

Upload local changes only.

Pushes local file changes to the cloud workspace. Never modifies local files, never downloads. Useful for CI scripts where you want a guaranteed one-direction operation.

Syntax

$filcaas up [workspace_path]

Options

Parameter	Type / Default	Description
workspace_path	PathDefault: current directory	The folder to upload.

Examples

# Upload current folder

$filcaas up

filcaasdown

Download cloud changes only.

Pulls the cloud version, overwriting local. Never uploads. Useful for disaster recovery when you want exactly what's in the cloud.

Syntax

$filcaas down [workspace_path]

Options

Parameter	Type / Default	Description
workspace_path	PathDefault: current directory	The folder to download into.

Examples

# Pull cloud copy into current folder

$filcaas down

filcaasrestore

Undo the last sync, up, or down.

Replays the single-slot backup created automatically before any sync operation. Useful when you regret a download that clobbered local edits, or when a sync produced unexpected files.

Syntax

$filcaas restore [workspace_path] [--dry-run]

Options

Parameter	Type / Default	Description
workspace_path	PathDefault: current directory	The folder to restore.
--dry-run	booleanDefault: false	Preview what would be restored without writing.

Examples

# Undo last sync

$filcaas restore

# See what restore would do first

$filcaas restore --dry-run

filcaaslogout

Clear local credentials.

Clears your saved token. Local workspace bindings are left alone.

Syntax

$filcaas logout

Examples

# Sign out from this machine

$filcaas logout

Workspaces

A workspace is a named set of agent config files that lives in your Filcaas cloud account. Each local folder is bound to one workspace, so commands like sync know what to push and pull.

You can rename or move the folder freely. The binding follows the directory. Every account starts with a 14-day free trial — full access, no credit card. Pro keeps everything running after that.

Agent config files we recognize

filcaas init detects whichever of these your project already uses, and syncs them as-is. When generating from scratch, it asks which tool you primarily use and writes only that file.

Claude CodeCLAUDE.md, .claude/

Cursor.cursorrules, .cursor/rules/

GitHub Copilot.github/copilot-instructions.md

Windsurf.windsurfrules, .windsurf/rules/

OpenCode / CodexAGENTS.md

AiderCONVENTIONS.md, .aider.conf.yml

Cline.clinerules

Continue.continue/

Zed.rules

Kimi CLIKIMI.md, .kimi/

Conflict handling

When the same file changed on both sides since the last sync, filcaas sync prompts you per file by default with [L] Keep local / [C] Keep cloud / [M] Merge. No silent overwrites — you decide each one. If only one side changed, sync just applies it; the prompt only appears for real conflicts.

Prefer silent newest-wins instead? The more recently edited version is kept and the loser is preserved as a backup in ~/.filcaas/projects/…/conflicts/. Switch the default once:

$filcaas config set conflict.strategy auto

To go back to the prompt (or override your saved preference for a single run), use:

$filcaas config unset conflict.strategy

$filcaas sync --interactive

$filcaas sync --auto

Non-TTY shells (e.g. CI) always fall back to newest-wins automatically — there's no terminal to prompt. If auto-resolve (yours or CI's) picked the wrong side, run filcaas resolve <path>. You'll get a [L] [C] [B] [M] prompt to flip the decision and push it.