Skip to main content

Scan

What is scan?​

A scan analyzes your project files and stores the results in a local CIAK database. During a scan, CIAK:

  • Walks your codebase
  • Extracts symbols (functions, classes, variables, files)
  • Tracks dependencies and relationships
  • Optionally generates vector embeddings for semantic search

The main CLI entry point is:

ciak scan [OPTIONS] [PATH]

Where you see it in the product​

  • CLI
    • ciak scan – basic scan of the current directory
    • ciak scan --embeddings – scan and generate embeddings
    • ciak scan --watch – watch for changes and rescan automatically
  • Cloud sync / SaaS portal
    • Cloud sync expects a scanned project (.ciak/database.db must exist).
    • The user portal’s project list and analytics are ultimately powered by scan results stored in the database.

When to run a scan​

  • After initializing a project
    • ciak init → ciak scan to create the initial index.
  • After making significant code changes
    • Run ciak scan again, or rely on --watch mode for continuous updates.
  • Before cloud sync
    • Cloud sync uses the local database populated by scans. If the database is missing, you’ll see errors like:
      • Local database not found. Run 'ciak scan' first.

Behavior and options​

Key behaviors from the CLI command reference:

  • Basic usage
    • ciak scan [PATH] – scan a directory (default: current directory .)
  • File selection
    • -f, --files <FILES> – scan specific files or directories
    • -r, --recursive – scan directories recursively
  • Watch mode
    • -w, --watch – watch for file changes and rescan automatically
    • --cloud-sync – in watch mode, push scan deltas to cloud automatically
    • --cloud-sync-profile <PROFILE> – cloud sync profile in watch mode (index_only, snippet_limited, full)
    • --watch-only – skip the initial scan if the database is already current
    • --watch-skip-threshold <SECONDS> – tolerance for database age
  • Embeddings
    • --embeddings – generate embeddings during scanning
    • --embedding-model <MODEL> – pick a specific embedding model
    • --incremental-embeddings – only update embeddings for changed files
  • Performance
    • --parallel / --sequential – choose parallel or sequential mode
    • --concurrency <COUNT> – number of concurrent workers
    • --batch-size <SIZE> – batch size for processing
    • --db-workers <COUNT> – concurrent database operations

The scan command writes its results to the project’s .ciak directory (for example .ciak/database.db).

Examples​

Example 1 – First scan of a project​

# From the project root
ciak init
ciak scan --embeddings

Expected result:

  • .ciak/database.db is created with symbols and relationships.
  • Embeddings are generated, enabling semantic search and better analytics.

Example 2 – Continuous scanning during development​

ciak scan --watch --embeddings

Expected result:

  • CIAK performs an initial scan.
  • As you edit files, CIAK picks up changes and updates the database and embeddings.

Example 3 – Prepare for cloud sync​

# Run a full scan with embeddings
ciak scan --embeddings

# Then sync to cloud
ciak cloud-sync full --path . --sync-profile full

Expected result:

  • Local database is populated by scan.
  • Cloud sync uploads the scanned project to the cloud API.

Example 4 – Watch mode with minimized cloud profile​

ciak scan --watch --cloud-sync --cloud-sync-profile snippet_limited

Expected result:

  • Local index stays fresh as files change.
  • Cloud sync runs continuously with snippet_limited data minimization.
  • Users keep snippet previews while avoiding full-context uploads.

Input and output examples​

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

One-time scan​

Input

ciak scan --embeddings

Output

Scanning project: /path/to/project
Indexing files...
Extracting symbols and relationships...
Generating embeddings...

Scan complete
  Files indexed: 248
  Symbols indexed: 3,912
  Relationships: 7,404
  Embeddings generated: 3,271
  Database: .ciak/database.db

Watch mode​

Input

ciak scan --watch --embeddings

Output

Initial scan complete. Watching for changes...
[watch] changed: src/auth/service.ts
[watch] rescanned: 1 file, updated 12 symbols, regenerated 9 embeddings
[watch] changed: src/auth/controller.ts
[watch] rescanned: 1 file, updated 6 symbols, regenerated 4 embeddings
  • license – required for cloud sync and advanced features.
  • sync – knowledge base sync from configuration files.
  • Cloud sync – uses the scanned data to populate the SaaS backend.

FAQ​

Do I need to run scan before every command?​

  • You don’t need to rescan before every CLI command.
  • You must have run at least one scan to populate .ciak/database.db.
  • Run another scan when you want the index and analytics to reflect new changes.

Does scan modify my source code?​

  • No. Scan only reads files and writes an internal database under .ciak/.

How long does a scan take?​

  • Depends on your project size and options.
  • You can speed things up with --parallel, --concurrency, and selective --files.