Skip to main content

What is sync?

In CIAK, the sync command is used to synchronize the knowledge base from configuration files into the local database.

It is separate from cloud sync:

  • ciak sync knowledge ... → imports knowledge entries from a JSON file (typically .ciak/knowledge.json).
  • ciak cloud-sync ... → sends scanned project data to the cloud API using your license.

This page focuses on the knowledge sync command.

Where you see it in the product​

  • CLI
    • ciak sync knowledge – sync knowledge entries from a config file into the CIAK database.
  • Knowledge workflows
    • You manage and edit .ciak/knowledge.json (or another file) and then run ciak sync knowledge to apply changes.
  • (Planned) User portal
    • Knowledge‑aware features (better search, suggestions) will be based on the synced knowledge entries stored in the database.

When to use sync​

Use ciak sync knowledge when:

  • You’ve edited .ciak/knowledge.json and want to push changes into CIAK.
  • You are installing or updating a knowledge template and need the database to reflect it.
  • You want to reset or re‑apply knowledge entries from a configuration file.

Behavior and options​

From the CLI command reference:

ciak sync knowledge [OPTIONS]

Options:

  • -f, --file <FILE> – Path to knowledge file (default: .ciak/knowledge.json).
  • -F, --force – Force re‑sync (clear existing user terms before importing).
  • -n, --dry-run – Show what would be synced without changing anything.
  • -v, --verbose – Verbose output.

Typical behavior:

  • Reads the specified JSON knowledge file.
  • Parses entries (technical terms, synonyms, acronyms, etc.).
  • Inserts or updates entries in the local CIAK database.
  • With --force, clears existing user terms before importing.

Examples​

Example 1 – Basic knowledge sync​

# Sync from default knowledge file
ciak knowledge init        # creates .ciak/knowledge.json template
# ... edit .ciak/knowledge.json ...
ciak sync knowledge

Expected result:

  • Entries defined in .ciak/knowledge.json are imported into the CIAK database.
  • Future searches and query‑understanding can leverage this knowledge.

Example 2 – Sync from a custom file​

ciak sync knowledge --file /path/to/my-knowledge.json

Expected result:

  • CIAK uses the provided file path instead of the default .ciak/knowledge.json.

Example 3 – Force re‑sync after a big change​

ciak sync knowledge --force

Expected result:

  • Existing user terms in the knowledge base are cleared.
  • Entries from the configuration file are imported fresh.

Input and output examples​

Representative CLI output (truncated; exact formatting may vary by version):

Dry-run preview​

Input

ciak sync knowledge --dry-run

Output

Reading .ciak/knowledge.json
Dry run enabled (no database changes)
Would import:
  terms: 12
  acronyms: 8
  synonyms: 17

Apply sync​

Input

ciak sync knowledge --verbose

Output

Syncing knowledge entries...
Inserted: 5
Updated: 9
Skipped (unchanged): 23
✓ Knowledge sync complete

Relationship to cloud sync​

  • ciak sync knowledge – local operation, importing configuration into the local database.
  • ciak cloud-sync – remote operation, sending project data (files, symbols, dependencies, embeddings) to the cloud API using your license.

In a full workflow for the SaaS platform:

  1. You define domain knowledge in .ciak/knowledge.json.
  2. You run ciak sync knowledge to import it locally.
  3. You run ciak scan to index your project.
  4. You run ciak cloud-sync full to push everything (project, symbols, knowledge context) to the cloud.
  • license – required for cloud sync and advanced features.
  • scan – builds the local project database.
  • Cloud sync – uses scanned data and license information to populate the SaaS backend.

FAQ​

Does sync modify my source code?​

  • No. It only reads configuration files and updates the CIAK database.

What happens if the knowledge file is invalid?​

  • The CLI will report parse/validation errors and will not apply partial changes.
  • Use --dry-run first if you want to see what would be imported without writing to the database.