zhongwei/gh-rawe-claude-dev-skills-firstspirit-fs-cli

Fork 0

Files

Zhongwei Li 0a3981a4f1 Initial commit

2025-11-30 08:50:01 +08:00

5.8 KiB

Raw Permalink Blame History

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:

../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

Login to (https://file.crownpeak.com)
Navigate to Downloads → FirstSpirit → Your Version
Find and Download fs-isolated-runtime.jar
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:

../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:

# 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:

java -version

You need Java 17 or higher. On macOS with multiple Java versions:

# 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):

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:

# In FirstSpirit ServerManager or ask your admin

Permission Denied on fs-cli

chmod +x .fs-cli/bin/fs-cli

Connection Failures

Verify server is running:
```
telnet $fshost $fsport
```
Check credentials in .env
Verify connection mode: HTTP vs HTTPS vs SOCKET
Check firewall/network access: Ensure your machine can reach the FS server

Test with fs-cli directly:

set -a && source .env && set +a && .fs-cli/bin/fs-cli.sh test

Download Failures

If GitHub download fails:

# 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:

.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:

# 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:

Learn the commands: Read fs-cli-usage.md for common fs-cli commands and usage examples
Understand template structure: Read fs-cli-sync-structure.md to understand the exported template structure
Start working: Use the FirstSpirit skill in Claude Code to work with templates
Optional: Set up version control for sync_dir/ if using external sync

Getting Help

If you encounter issues:

Run diagnostics: bash validate-environment.sh
Check this guide's troubleshooting section
Review fs-cli README: .fs-cli/README.txt
Check FirstSpirit server logs
Contact your FirstSpirit administrator

5.8 KiB Raw Permalink Blame History