zhongwei/gh-rawe-claude-dev-skills-firstspirit-fs-cli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:50:01 +08:00
commit 0a3981a4f1
12 changed files with 1496 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

233
skills/firstspirit-fs-cli/reference/fs-cli-installation-guide.md Normal file
View File

@@ -0,0 +1,233 @@
# FirstSpirit CLI Installation Guide
This guide walks you through setting up fs-cli for your FirstSpirit project.
## Prerequisites
- **Java 17 or higher** installed locally
- **JAVA_HOME** environment variable set (recommended)
- Access to a FirstSpirit server
- FirstSpirit user credentials
## Setup Steps
### 1. Run the Setup Script
run the setup script:
```bash
../scripts/setup-fs-cli.sh
```
BE AWARE that this script is interactive and relative to this file here.
This script will:
- Prompt for fs-cli version (default: 4.8.6)
- Download and extract fs-cli to `.fs-cli/`
- Prompt for your FirstSpirit version
- Guide you through obtaining `fs-isolated-runtime.jar`
- Create the `.env` and `.env.example` files
- Update `.gitignore`
### 2. Obtain fs-isolated-runtime.jar
**This is the only manual step.**
The `fs-isolated-runtime.jar` file must match your FirstSpirit server version exactly.
#### Option A: From FirstSpirit Server
The fs-isolated-runtime jar is located in the server installation directory `[serverRoot]/data/fslib`
#### Option B: From Crownpeaks file server
1. Login to (https://file.crownpeak.com)
2. Navigate to Downloads → FirstSpirit → Your Version
3. Find and Download `fs-isolated-runtime.jar`
4. Copy to: `.fs-cli/lib/fs-isolated-runtime.jar`
**Important**: The jar version must match your FirstSpirit server version exactly (e.g., 2025.01, 2024.09, etc.)
### 3. Validate Environment
Run the validation script:
```bash
../scripts/validate-environment.sh
```
BE AWARE that this script is elative to this file here.
This checks:
- Java 17+ is installed
- JAVA_HOME is set (optional but recommended)
- fs-cli is extracted properly
- fs-isolated-runtime.jar is in place
- fs-cli can run
### 4. Start Using fs-cli
Once validation passes, you can:
- Use the FirstSpirit skill in Claude Code
- Run fs-cli directly: `.fs-cli/bin/fs-cli`
- Use export/import commands
## Configuration
All configuration is stored in `.env`:
```bash
# FirstSpirit Server Configuration
fshost=localhost
fsport=8000
fsmode=HTTP
fsproject=my-project
# FirstSpirit Credentials (KEEP SECRET - DO NOT COMMIT)
fsuser=Admin
fspwd=your_password
# fs-cli Configuration (for reference only, not used by fs-cli)
FS_CLI_VERSION=4.8.6
FS_VERSION=2025.01
```
**Never commit `.env` to git!** Use `.env.example` as a template for your team.
## Troubleshooting
### Java Version Issues
Check your Java version:
```bash
java -version
```
You need Java 17 or higher. On macOS with multiple Java versions:
```bash
# Set Java 17
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
# Or Java 21
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
```
Add to your shell profile (`~/.zshrc` or `~/.bashrc`):
```bash
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
```
### fs-isolated-runtime.jar Version Mismatch
**Symptom**: Connection errors or runtime exceptions
**Solution**: Ensure jar version exactly matches your FirstSpirit server version. Check your server version:
```bash
# In FirstSpirit ServerManager or ask your admin
```
### Permission Denied on fs-cli
```bash
chmod +x .fs-cli/bin/fs-cli
```
### Connection Failures
1. **Verify server is running**:
```bash
telnet $fshost $fsport
```
2. **Check credentials** in `.env`
3. **Verify connection mode**: HTTP vs HTTPS vs SOCKET
4. **Check firewall/network access**: Ensure your machine can reach the FS server
5. **Test with fs-cli directly**:
```bash
set -a && source .env && set +a && .fs-cli/bin/fs-cli.sh test
```
### Download Failures
If GitHub download fails:
```bash
# Manually download from:
# https://github.com/e-Spirit/FSDevTools/releases/download/VERSION/fs-cli-VERSION.tar.gz
# Extract manually:
tar -xzf fs-cli-VERSION.tar.gz -C .fs-cli/
```
## Directory Structure
After setup:
```
your-project/
├── .env # Your config (gitignored)
├── .env.example # Template (committed)
├── .gitignore # Ignores .fs-cli/ and .env
├── .fs-cli/ # Gitignored
│ ├── bin/
│ │ └── fs-cli # The CLI executable
│ ├── lib/
│ │ └── fs-isolated-runtime.jar # You provide (version-specific)
│ └── .setup-marker # Tracks setup state (fs-cli version, FS version)
├── sync_dir/ # FirstSpirit templates (exported)
└── scripts/ # Optional convenience scripts
```
## Working with Multiple Environments
Each project connects to one FirstSpirit server version. If you have multiple environments (dev, staging, prod) with the same FS version, you can use different .env files:
```bash
.env # Default environment
.env.prod # Production
.env.staging # Staging
# Switch environments by sourcing different .env files:
set -a && source .env.prod && set +a && .fs-cli/bin/fs-cli.sh -sd sync_dir/ export
```
**Note**: All environments in a project should use the same FirstSpirit version since the fs-isolated-runtime.jar is version-specific.
## Advanced: Adding Custom JARs
For future custom functionality:
```bash
# Add your custom JAR to fs-cli classpath
cp your-custom-tool.jar .fs-cli/lib/
```
The fs-cli will automatically include all JARs in the lib folder.
## Next Steps
Once installation is complete:
1. **Learn the commands**: Read `fs-cli-usage.md` for common fs-cli commands and usage examples
2. **Understand template structure**: Read `fs-cli-sync-structure.md` to understand the exported template structure
3. **Start working**: Use the FirstSpirit skill in Claude Code to work with templates
4. **Optional**: Set up version control for `sync_dir/` if using external sync
## Getting Help
If you encounter issues:
1. Run diagnostics: `bash validate-environment.sh`
2. Check this guide's troubleshooting section
3. Review fs-cli README: `.fs-cli/README.txt`
4. Check FirstSpirit server logs
5. Contact your FirstSpirit administrator

410
skills/firstspirit-fs-cli/reference/fs-cli-sync-structure.md Normal file
View File

@@ -0,0 +1,410 @@
# FirstSpirit FS-CLI Export/Sync Directory Structure
## Overview
This document describes the structure and file formats used when exporting FirstSpirit templates using FS-CLI (FSDevTools). The export creates a hierarchical file system structure that mirrors the FirstSpirit project structure, preserving all template configurations, forms, rules, and output channels.
## General Structure
The FS-CLI export follows a consistent pattern:
```
sync_dir/
├── .FirstSpirit/ # Export metadata (do not version control)
│ ├── Files_*.txt # List of all exported files with checksums
│ └── Import_*.txt # Import metadata
│
└── TemplateStore/ # Template Store root
├── FormatTemplates/ # Text formatting templates
├── LinkTemplates/ # Link templates
├── PageTemplates/ # Page templates
├── SectionTemplates/ # Section templates (content modules)
├── Schemes/ # Database schema templates
├── Scripts/ # Script templates
└── Workflows/ # Workflow definitions
```
### Key Principles
1. **Folder hierarchy mirrors FirstSpirit structure**: The file system replicates the exact folder structure from the FirstSpirit project
2. **One folder per element**: Each FirstSpirit template/element gets its own directory
3. **Consistent file naming**: Files use standardized names based on their purpose
4. **Multiple files per template**: Templates are decomposed into separate files for different aspects (form, output, rules, etc.)
## Template Store Structure
### Template Types and Locations
| Template Type | Directory | Purpose |
|--------------|-----------|---------|
| **Page Templates** | `TemplateStore/PageTemplates/` | Define page framework and structure |
| **Section Templates** | `TemplateStore/SectionTemplates/` | Content modules inserted into pages |
| **Format Templates** | `TemplateStore/FormatTemplates/` | Text formatting options for editors |
| **Link Templates** | `TemplateStore/LinkTemplates/` | Link type configurations |
| **Table Templates** | `TemplateStore/Schemes/` | Database schema templates |
| **Script Templates** | `TemplateStore/Scripts/` | BeanShell scripts and functions |
| **Workflows** | `TemplateStore/Workflows/` | Approval and release workflows |
## File Types Reference
Each template directory contains a combination of the following files, depending on the template type:
### Core Files (All Templates)
#### StoreElement.xml
**Purpose**: Core template metadata and configuration
**Contains**:
- Template ID (`id` attribute) - unique identifier
- Template reference name (`filename` or `name` attribute)
- Template type (`type` attribute: `page`, `section`, `format`, etc.)
- Display names (multilingual via `<LANG>` elements)
- Channel/extension mappings (`<EXTENSION>` elements)
- Template body definitions (`<TEMPLATEBODY>`)
- Format template style definitions (`<style>` for format templates)
#### FS_Files.txt
**Purpose**: File registry with metadata for all files in the template directory
**Contains**: Tab-delimited list with checksum, file size, timestamp, MIME type, and filename for each file
#### FS_Info.txt
**Purpose**: Additional metadata about the template element
**Contains**: Template information, creation/modification dates, author information
#### FS_References.txt
**Purpose**: Dependency tracking
**Contains**: References to other FirstSpirit elements that this template depends on or uses
### Form Definition Files
#### GomSource.xml
**Purpose**: Form definition (GOM = GUI Object Model)
**Contains**:
- Input component definitions (CMS_INPUT_*, FS_CATALOG, FS_INDEX, etc.)
- Form field configurations
- Labels and descriptions (multilingual via `<LANGINFO>`)
- Layout and organization
- Default values
#### GomDefaults.xml
**Purpose**: Default values for GOM form fields (optional)
**Found in**: Style/Format templates primarily
**Contains**: Default values for form fields
### Output Channel Files
#### ChannelSource_[CHANNEL]_[EXTENSION].[EXTENSION]
**Purpose**: Template output for specific delivery channels
**Naming pattern**: `ChannelSource_<ChannelName>_<extension>.<extension>`
**Common examples**:
- `ChannelSource_HTML_html.html` - HTML output channel
- `ChannelSource_XML_xml.xml` - XML output channel
- `ChannelSource_JSON_json.json` - JSON output channel
**Contains**: FirstSpirit template syntax with output logic (HTML, XML, or other formats)
### Rule Definition Files
#### Ruleset.xml
**Purpose**: Dynamic form behavior and validation rules
**Contains**:
- Conditional visibility rules
- Field dependency rules
- Validation rules (SAVE, RELEASE, INFO severity)
- Dynamic value calculations
- Multi-language support rules
### Preview/Snippet Files
These files define how templates appear in preview mode and in template selection dialogs.
#### SnippetThumb.txt
**Purpose**: Thumbnail/icon preview
**Contains**: Template syntax to generate small preview image or icon
#### SnippetHeader.txt
**Purpose**: Header/title preview
**Contains**: Template syntax to generate preview title (often just the headline field)
#### SnippetExtract.txt
**Purpose**: Content extract preview
**Contains**: Template syntax to generate preview text/excerpt
**Example**:
```
$CMS_IF(!pt_headline.isEmpty)$
$CMS_VALUE(pt_headline.toText(false))$
$CMS_END_IF$
```
### Workflow-Specific Files
#### Workflow.xml
**Purpose**: Complete workflow definition
**Contains**:
- States (start, end, intermediate states)
- Activities (tasks, actions)
- Transitions (connections between states)
- Email configurations
- Permissions and rights
- User/group assignments
- Scripting logic
**Structure**: Java object serialization format describing the workflow graph
**Key Components**:
- **States**: Workflow stages with permissions and duration
- **Activities**: Tasks users perform
- **Transitions**: Connections with email notifications and rights
- **Coordinates**: Visual layout positions (x, y coordinates)
#### ViewScript.txt
**Purpose**: Custom workflow display/view logic (optional)
**Contains**: BeanShell script for custom workflow UI
## Directory Organization by Template Type
### Page Templates
```
PageTemplates/
└── pt_standard_page/
├── StoreElement.xml # Template metadata
├── GomSource.xml # Form definition
├── Ruleset.xml # Form rules
├── ChannelSource_HTML_html.html # HTML output
├── SnippetThumb.txt # Thumbnail preview
├── SnippetHeader.txt # Header preview
├── SnippetExtract.txt # Extract preview
├── FS_Files.txt # File registry
├── FS_Info.txt # Metadata
└── FS_References.txt # Dependencies
```
### Section Templates
```
SectionTemplates/
└── st_text_image_module/
├── StoreElement.xml # Template metadata
├── GomSource.xml # Form definition
├── Ruleset.xml # Form rules
├── ChannelSource_HTML_html.html # HTML output
├── SnippetThumb.txt # Thumbnail preview
├── SnippetHeader.txt # Header preview
├── SnippetExtract.txt # Extract preview
├── FS_Files.txt # File registry
├── FS_Info.txt # Metadata
└── FS_References.txt # Dependencies
```
### Format Templates
```
FormatTemplates/
├── h1/
│ ├── StoreElement.xml # Format definition with style
│ ├── ChannelSource_HTML_html.html # HTML rendering
│ ├── FS_Files.txt
│ ├── FS_Info.txt
│ └── FS_References.txt
│
└── common_format_templates/ # Folder grouping
├── StoreElement.xml # Folder metadata
├── FS_Files.txt
├── FS_Info.txt
├── FS_References.txt
│
├── default_style_template/
│ ├── StoreElement.xml # Style template definition
│ ├── GomSource.xml # Style configuration form
│ ├── GomDefaults.xml # Default style values
│ ├── Ruleset.xml
│ ├── ChannelSource_HTML_html.html
│ ├── FS_Files.txt
│ ├── FS_Info.txt
│ └── FS_References.txt
│
└── p/ # Paragraph format
├── StoreElement.xml
├── ChannelSource_HTML_html.html
└── ...
```
### Workflows
```
Workflows/
└── assign_task/
├── StoreElement.xml # Workflow metadata
├── Workflow.xml # Workflow definition (states, transitions)
├── GomSource.xml # Form for workflow parameters
├── Ruleset.xml # Form rules
├── ViewScript.txt # Custom view script (optional)
├── SnippetThumb.txt # Preview files
├── SnippetHeader.txt
├── SnippetExtract.txt
├── FS_Files.txt
├── FS_Info.txt
└── FS_References.txt
```
## Metadata Directory: .FirstSpirit
**Location**: `.FirstSpirit/` at the root of the sync directory
**Purpose**: Contains internal metadata required for successful synchronization between file system and FirstSpirit server
**Important**: Do NOT version control this directory. It contains session-specific information.
### Files
#### Files_[sessionid]_[revision].txt
**Purpose**: Complete file registry for the export
**Contains**: Tab-delimited entries with reference IDs and file information (checksum, size, timestamp, MIME type, filename)
#### Import_[sessionid]_[revision].txt
**Purpose**: Import instructions and metadata for re-importing into FirstSpirit
## Template Identification
### Finding Templates
Templates are located by type in their respective directories:
| What to find | Where to look | Identifier |
|-------------|---------------|------------|
| Page template by name | `PageTemplates/[name]/` | Directory name matches template reference name |
| Section template by name | `SectionTemplates/[name]/` | Directory name matches template reference name |
| Format template by name | `FormatTemplates/[name]/` | Directory name matches format name |
| Template by ID | Search `StoreElement.xml` files for `id` attribute | Unique numeric ID |
| Template display name | Look in `StoreElement.xml` → `<LANG>` elements | Multilingual display names |
### Template Reference Names
The directory name matches the template's **reference name** (UID name) in FirstSpirit:
- `pt_standard_page` → Page Template with reference name "pt_standard_page"
- `st_text_image_module` → Section Template with reference name "st_text_image_module"
### Template IDs
Each template has two IDs in `StoreElement.xml`:
- `id` - Element instance ID
- `templateid` - Template definition ID (for page/section templates)
## Information Access Guide
### How to Find Specific Information
| Information Needed | File to Check | Location in File |
|-------------------|---------------|------------------|
| **Template display name** | `StoreElement.xml` | `<LANG displayname="..." language="EN"/>` |
| **Template reference name** | `StoreElement.xml` | `filename` or `name` attribute |
| **Template ID** | `StoreElement.xml` | `id` attribute |
| **Form fields** | `GomSource.xml` | `<CMS_INPUT_*>` elements |
| **Field labels** | `GomSource.xml` | `<LANGINFO lang="*" label="..."/>` |
| **Available format templates** | `GomSource.xml` in DOM fields | `<FORMATS><TEMPLATE name="..."/></FORMATS>` |
| **HTML output** | `ChannelSource_HTML_html.html` | Entire file |
| **Template variables** | `ChannelSource_HTML_html.html` | `<CMS_HEADER>` section |
| **Form rules** | `Ruleset.xml` | `<RULE>` elements |
| **Dependencies** | `FS_References.txt` | List of referenced elements |
| **Workflow states** | `Workflow.xml` | `<FIELD name="states">` section |
| **Workflow transitions** | `Workflow.xml` | `<FIELD name="transitions">` section |
## Template Set Configuration
**Location**: `StoreElement.xml` → `<EXTENSION>` element
**Attributes**:
- `file` - File extension for generated files
- `link` - Link extension
- `templateSet` - Template set ID
- `replaceable` - Whether extension can be changed
## Common Use Cases
### 1. Finding All Section Templates
```bash
find sync_dir/TemplateStore/SectionTemplates -name "StoreElement.xml" -type f
```
### 2. Extracting Template Display Names
```bash
grep -r "displayname=" sync_dir/TemplateStore/*/*/StoreElement.xml
```
### 3. Finding Templates Using a Specific Format
```bash
grep -r '<TEMPLATE name="h1"/>' sync_dir/TemplateStore/*/*/GomSource.xml
```
### 4. Listing All Form Fields in a Template
```bash
grep -o 'name="[^"]*"' sync_dir/TemplateStore/PageTemplates/pt_standard_page/GomSource.xml
```
### 5. Finding All HTML Output Templates
```bash
find sync_dir/TemplateStore -name "ChannelSource_HTML_html.html" -type f
```
## Best Practices
### Version Control
1. **DO** version control all template files in `TemplateStore/`
2. **DO NOT** version control `.FirstSpirit/` directory
3. **DO** commit `StoreElement.xml`, `GomSource.xml`, `ChannelSource_*`, and `Ruleset.xml` files
4. **CONSIDER** whether to version `FS_Files.txt` (contains checksums that change frequently)
### Template Development
1. **Naming**: Use consistent prefixes (e.g., `pt_` for page templates, `st_` for section templates)
2. **Organization**: Group related format templates in folders (like `common_format_templates/`)
3. **Documentation**: Use meaningful `displayname` attributes in multilingual `<LANG>` elements
4. **Dependencies**: Check `FS_References.txt` to understand template dependencies
### Editing Exported Files
1. **StoreElement.xml**: Edit carefully, preserve IDs unless creating new templates
2. **GomSource.xml**: Standard XML, can be edited directly
3. **ChannelSource files**: Edit freely, contains your template output logic
4. **Ruleset.xml**: Edit rules following FirstSpirit rule syntax
5. **Workflow.xml**: Complex Java serialization format, prefer editing in SiteArchitect
### Re-importing
1. Maintain the exact directory structure
2. Keep `StoreElement.xml` IDs consistent for updates
3. Ensure all referenced templates exist
4. Validate XML syntax before import
## File Type Summary Table
| File | Required | Template Types | Editable | Purpose |
|------|----------|----------------|----------|---------|
| `StoreElement.xml` | Yes | All | Yes (carefully) | Template metadata and configuration |
| `GomSource.xml` | For templates with forms | Page, Section, Workflow, Style | Yes | Form definition (input components) |
| `GomDefaults.xml` | No | Style/Format | Yes | Default form values |
| `Ruleset.xml` | No | Page, Section, Workflow | Yes | Dynamic form rules |
| `ChannelSource_*.html` | For output templates | Page, Section, Format | Yes | Output channel templates |
| `Workflow.xml` | Yes | Workflow | No (use SiteArchitect) | Workflow definition |
| `ViewScript.txt` | No | Workflow | Yes | Custom workflow view |
| `Snippet*.txt` | No | Page, Section | Yes | Preview content |
| `FS_Files.txt` | Yes | All | No (auto-generated) | File registry |
| `FS_Info.txt` | Yes | All | No (auto-generated) | Element metadata |
| `FS_References.txt` | Yes | All | No (auto-generated) | Dependency tracking |
## References
- **Official Documentation**: https://docs.e-spirit.com/odfs/edocs/sync/
- **FS-CLI Tool**: https://github.com/e-Spirit/FSDevTools
- **Template Development**: https://docs.e-spirit.com/odfs/template-develo/
- **External Synchronization**: https://docs.e-spirit.com/odfs/edocs/sync/how/4-export/

152
skills/firstspirit-fs-cli/reference/fs-cli-usage.md Normal file
View File

@@ -0,0 +1,152 @@
# FS-CLI Usage Guide
## Prerequisites
- Java Runtime Environment (JRE) 17 or higher
- FirstSpirit 5.2.231105 or higher
- Correct `JAVA_HOME` environment variable set
## Environment Variables
FS-CLI supports environment variables to simplify command execution:
| Variable | Description | Default |
|-------------|------------------------------------------------|-------------|
| `fshost` | FirstSpirit host address | `localhost` |
| `fsport` | FirstSpirit port number | `8000` |
| `fsmode` | Connection mode: HTTP, HTTPS, or SOCKET | `HTTP` |
| `fsuser` | FirstSpirit user account | - |
| `fspwd` | FirstSpirit user password | - |
| `fsproject` | FirstSpirit project name | - |
**IMPORTANT:** These environment variables are already set in the .env file in the project root directory for convenience.
### Setup Environment Variables
The `.env` file should use standard format (without `export` keyword). Use `set -a; source .env; set +a` before running fs-cli commands to properly export these variables.
## Common Commands
### Test Connection
Test connection to FirstSpirit server:
```bash
set -a && source .env && set +a && .fs-cli/bin/fs-cli.sh test
```
### Export Templates
Export only templates (no content, media, etc.):
```bash
set -a && source .env && set +a && .fs-cli/bin/fs-cli.sh -sd sync_dir/ export -- templatestore
```
### Export Single Template by ID
Export a specific template by its UID:
```bash
set -a && source .env && set +a && .fs-cli/bin/fs-cli.sh -sd sync_dir/ export -- sectiontemplate:st_text_image_module
```
**Template Type Prefixes:**
- `sectiontemplate:` - Section templates
- `pagetemplate:` - Page templates
- `formattemplate:` - Format templates
- `linktemplate:` - Link templates
- `workflow:` - Workflows
- `script:` - Scripts
**Examples:**
```bash
# Export a section template
set -a && source .env && set +a && .fs-cli/bin/fs-cli.sh -sd sync_dir/ export -- sectiontemplate:st_text_image_module
# Export a page template
set -a && source .env && set +a && .fs-cli/bin/fs-cli.sh -sd sync_dir/ export -- pagetemplate:pt_standard_page
# Export multiple specific templates
set -a && source .env && set +a && .fs-cli/bin/fs-cli.sh -sd sync_dir/ export -- sectiontemplate:st_text_image_module pagetemplate:pt_standard_page
```
**What Happens to Previously Exported Templates:**
When you export a specific template by ID, fs-cli will **remove all other templates** from `sync_dir/` that are not part of the current export. This keeps the sync directory focused on only the templates you specified.
- **Before**: `sync_dir/` contains all previously exported templates
- **After**: `sync_dir/` contains **only** the template(s) you just exported
- **Deleted**: All other templates are removed from `sync_dir/` (not from the server!)
**To keep existing templates and add more**, use the `--keepObsoleteFiles` flag:
```bash
set -a && source .env && set +a && .fs-cli/bin/fs-cli.sh -sd sync_dir/ export --keepObsoleteFiles -- sectiontemplate:st_text_image_module
```
### Export Specific Element by UID
Export a single element by its unique ID:
```bash
set -a && source .env && set +a && .fs-cli/bin/fs-cli.sh -sd sync_dir/ export -uid homepage
```
Replace `homepage` with the UID of the element you want to export.
### Import Templates
Import templates from local sync directory to FirstSpirit server:
```bash
set -a && source .env && set +a && .fs-cli/bin/fs-cli.sh -sd sync_dir/ import
```
**Requirements:**
- Sync directory must exist
- Sync directory must contain valid `TemplateStore/` structure (see `fs-cli-sync-structure.md`)
- User must have write permissions in FirstSpirit project
**Important:** Import overwrites existing templates with the same names in FirstSpirit.
### Dry Run Import
Test import without making changes to the server:
```bash
set -a && source .env && set +a && .fs-cli/bin/fs-cli.sh -sd sync_dir/ import --dry-run
```
Use this to verify what would be imported before actually doing it.
## Alternative: Using Explicit Parameters
If you prefer not to use environment variables, you can specify all parameters explicitly:
```bash
.fs-cli/bin/fs-cli.sh \
-h localhost \
-port 8000 \
-u admin \
-pwd your-password \
-m HTTP \
-p my-project \
-sd sync_dir/ \
export
```
**However**, using environment variables (via `.env` file) is **strongly recommended** for:
- Security (credentials not in command history)
- Convenience (shorter commands)
- Consistency (same config across commands)
## Notes
- **Always use `set -a && source .env && set +a` before running commands** to properly export environment variables
- When using environment variables, connection parameters (`-h`, `-port`, `-u`, `-pwd`, `-m`, `-p`) can be omitted
- The sync directory is in the project root subfolder `sync_dir/`
- Global options like `-sd` must come BEFORE the command (e.g., `-sd sync_dir/ export` not `export -sd sync_dir/`)
- Import overwrites existing templates with the same names in FirstSpirit
- Export creates/overwrites files in the sync directory
- Use `--dry-run` with import to test safely before applying changes