مرجع أوامر سطر الأوامر (CLI)
دليل شامل لكافة أوامر الطرفية الـ 15 المتاحة داخل indieinabox.php. بدءاً من جدولة المهام الآلية cron وجلب الخلاصات، وصولاً إلى النسخ الاحتياطي المشفر بضغطة زر والتحديث الآمن.
Global Syntax & Execution
All CLI commands are invoked directly through PHP with the standalone binary:
php indieinabox.php [command] [options] [arguments]
Run php indieinabox.php help at any time to list all registered commands and their descriptions.
00 // php indieinabox.php --serve
Starts PHP's built-in web server with internal routing dispatched to indieinabox.php. Ideal for local development, content authoring, or low-traffic personal sites.
| Option / Flag | Type | Default | Description |
|---|---|---|---|
| --serve | FLAG | false | Activates the built-in HTTP development server daemon. |
| --port <int> | PARAM | 8080 | Port to bind the web server (alias: -p). |
| --host <ip> | PARAM | 127.0.0.1 | Network interface to bind (use 0.0.0.0 for Docker containers). |
$ php indieinabox.php --serve --port 8080
[2026-09-22 10:00:00] PHP 8.3.6 Development Server (http://127.0.0.1:8080) started
[2026-09-22 10:00:02] 127.0.0.1:54120 [200]: GET /
[2026-09-22 10:00:04] 127.0.0.1:54124 [200]: GET /admin/config
01 // setup
Initializes the site database, author identity, administrative password, and default configuration. Can be run interactively or in unattended headless mode using command flags.
| Option / Flag | Type | Default | Description |
|---|---|---|---|
| --name <str> | PARAM | Indie In A Box | Site title / publication name (alias: --sitename). |
| --fqdn <url> | PARAM | http://localhost:8080 | Fully Qualified Domain Name / root canonical URL (alias: --url). |
| --password <str> | PARAM | auto-generated | Admin & IndieAuth password. If omitted, a secure 24-character random password is generated and printed. |
| --author <str> | PARAM | Site Author | Display name of the site author for h-card and ActivityPub Actor. |
| --db <path> | PARAM | data/indieinabox.sqlite | SQLite database file path (alias: --database). |
| --data-dir <dir> | PARAM | data | Persistent storage directory for feeds, database, and local caches. |
| --lang <code> | PARAM | en | Primary locale code (e.g. en, pt-BR, es). |
| --force | FLAG | false | Overwrites existing configuration and re-runs database setup without confirmation. |
$ php indieinabox.php setup \
--name "Lumen Cyberdeck" \
--fqdn "https://lumen.pink" \
--author "Lumen Pink" \
--password "SuperSecretPassphrase2026!" \
--lang "en"
[OK] SQLite database initialized at data/indieinabox.sqlite
[OK] Migrations applied: 18/18 up to date
[OK] Site profile registered: Lumen Pink
[OK] Admin password configured successfully!
02 // build
Executes the static compilation pipeline. Scans content, builds HTML pages, compiles Gemini capsules (.gmi), Gophermaps, RSS 2.0, Atom, JSON Feeds, and Twtxt timelines, and runs garbage collection.
| Option / Flag | Type | Default | Description |
|---|---|---|---|
| -s, --site | FLAG | true | Compiles HTML pages to public_html/. |
| -f, --feeds | FLAG | true | Generates syndication feeds (RSS, Atom, JSON, Twtxt). |
| -a, --assets | FLAG | true | Copies static CSS, JS, and font assets. |
| -M, --media | FLAG | true | Synchronizes uploaded user media and Microsub avatars. |
| -m, --modern | FLAG | true | Compiles Gemini capsules (public_gemini/) and Gopher (public_gopher/). |
$ php indieinabox.php build
Scanning content directory...
Virtualizing posts and taxomies...
Built 142 HTML documents
Built 142 Gemini (.gmi) capsules
Built 142 Gophermaps
Generating feeds: rss.xml, atom.xml, twtxt.txt, feed.json
Copying assets and media files...
Running Garbage Collector...
+----------------------------------+-----------------+
| Task | Time (ms) |
+----------------------------------+-----------------+
| Scan + Virtualize | 12.13 |
| Generate HTML/GMI/Gopher | 285.36 |
| Generate Feeds | 3.00 |
| Copy Assets | 0.08 |
| Copy Media | 6.66 |
| Copy Static Files | 0.02 |
| Garbage Collect | 11.24 |
+----------------------------------+-----------------+
| TOTAL BUILD TIME | 318.49 |
+----------------------------------+-----------------+
Build complete
03 // cron
Executes scheduled asynchronous background pipelines. Handles federated ActivityPub inbox processing, delivery of outbox activities, outgoing Webmention pings, and syndication to Internet Archive.
| Option / Flag | Type | Default | Description |
|---|---|---|---|
| --only <task> | PARAM | all | Limits execution to a specific worker: activitypub, webmentions, or archive. |
# Run every 5 minutes in server crontab:
*/5 * * * * cd /var/www/myblog && php indieinabox.php cron >> data/cron.log 2>&1
04 // fetch
Microsub feed fetcher. Traverses active subscriptions across RSS, Atom, JSON Feed, and Twtxt channels and ingests new entries into the local reader database.
| Alias | Type | Description |
|---|---|---|
| microsub:fetch | ALIAS | Alternative command name registered in the CLI kernel. |
$ php indieinabox.php fetch
Fetching feeds...
[POLL] https://aaronparecki.com/feed.xml -> 3 new items
[POLL] https://werd.io/feed -> 0 new items
[POLL] https://twtxt.net/user/alice/twtxt.txt -> 1 new item
[OK] Microsub database updated successfully (4 items ingested).
05 // post
Creates and publishes content directly from the command line. Automatically assigns post kinds (note, article, reply), processes hashtags, and triggers outgoing syndication.
| Subcommand / Option | Type | Default | Description |
|---|---|---|---|
| create | SUBCOMMAND | required | Creates a new post entry. |
| --text <content> | PARAM | required | Text content or markdown of the post. |
| --media <file> | PARAM | none | Path to image, audio, or file attachment to upload. |
$ php indieinabox.php post create \
--text "Hacking on the new single-file IndieWeb engine! #indieweb #php" \
--media ~/photos/desk.jpg
[OK] Post created: 2026-09-22-hacking-on-the-new-single-file.md
[OK] Media attached: desk.jpg (processed & signed)
[OK] Webmentions dispatched: 2 targets pinged
[OK] ActivityPub outbox updated: Create(Note) announced to 48 followers
06 // profile
Updates site identity, bio, social rel-me links, avatar portrait, and profile header banner image.
| Subcommand / Option | Type | Description |
|---|---|---|
| edit | SUBCOMMAND | Modifies profile metadata text fields. |
| --username <str> | PARAM | Fediverse handle username (e.g. @lumen). |
| --name <str> | PARAM | Full display name of author. |
| --bio <str> | PARAM | Short biographical text summary. |
| media | SUBCOMMAND | Updates profile images. |
| --avatar <path> | PARAM | Path to portrait avatar image. |
| --background <path> | PARAM | Path to header banner background image. |
$ php indieinabox.php profile edit --username "lumen" --name "Lumen Pink" --bio "Cyberpunk hacker & IndieWeb builder"
$ php indieinabox.php profile media --avatar assets/avatar.png --background assets/banner.jpg
[OK] Profile updated: @lumen (Lumen Pink)
[OK] Media assets optimized and copied to public_media/
07 // config
Direct inspection and manipulation of runtime site configuration key-value pairs stored in the SQLite database.
| Subcommand / Option | Type | Description |
|---|---|---|
| get --key <str> | PARAM | Prints the current stored value for the specified key. |
| set --key <k> --value <v> | PARAM | Persists a new value for the configuration key. |
$ php indieinabox.php config get --key active_theme
default
$ php indieinabox.php config set --key active_theme --value cyber-dark
[OK] Configuration updated: active_theme = 'cyber-dark'
08 // test-links
Static link crawler. Scans generated HTML documents to detect dead hyperlinks, broken relative paths, and unresolvable external URLs.
| Option / Flag | Type | Default | Description |
|---|---|---|---|
| --skip-external | FLAG | false | Audits internal links only; avoids issuing outbound HTTP requests. |
| --internal-only | FLAG | false | Alias for --skip-external. |
| --report <path> | PARAM | none | Exports an audit report in JSON or Markdown to the specified file path. |
$ php indieinabox.php test-links --skip-external
Scanning 142 HTML files in public_html/...
Crawling 1,280 internal links...
[OK] 1,280 links verified. 0 broken links detected! (Exit code: 0)
09 // migrate
Database schema version control. Applies pending SQLite migrations, rolls back recent batches, or inspects current migration states.
| Option / Flag | Type | Default | Description |
|---|---|---|---|
| --status | FLAG | false | Prints a table of all migrations with execution status and timestamp. |
| --rollback | FLAG | false | Rolls back the last executed migration batch. |
| --steps <int> | PARAM | 1 | Number of migration steps to rollback when --rollback is enabled. |
$ php indieinabox.php migrate --status
+-------------------------------------------------------+---------+---------------------+
| Migration | Status | Executed At |
+-------------------------------------------------------+---------+---------------------+
| 2026_09_01_000001_create_posts_table | Ran | 2026-09-01 12:00:00 |
| 2026_09_05_000002_create_activitypub_actors_table | Ran | 2026-09-05 14:15:30 |
| 2026_09_12_000003_create_moderation_rules_table | Ran | 2026-09-12 18:22:11 |
| 2026_09_20_000004_create_ai_translation_cache_table | Ran | 2026-09-20 09:40:02 |
+-------------------------------------------------------+---------+---------------------+
All migrations up to date.
10 // backup
Creates a full point-in-time ZIP backup containing the SQLite database, markdown contents, and media attachments.
| Option / Flag | Type | Default | Description |
|---|---|---|---|
| --no-content | FLAG | false | Excludes the markdown content/ directory from the archive. |
| --no-media | FLAG | false | Excludes the public_media/ directory to produce a lightweight backup. |
$ php indieinabox.php backup
[BACKUP] Snapshotting database: data/indieinabox.sqlite...
[BACKUP] Archiving markdown posts (142 files)...
[BACKUP] Archiving user media attachments (38 files)...
[OK] Archive created: data/backups/indieinabox_backup_2026-09-22_10-15-00.zip (14.2 MB)
11 // export
Generates a portable, cryptographically verified export bundle (.tar.gz or .zip) complete with a SHA-256 manifest for migrating between servers.
| Argument / Option | Type | Default | Description |
|---|---|---|---|
| [output-file] | ARG | timestamped | Positional filename or --output <path>. |
| --no-content | FLAG | false | Omits markdown content folder. |
| --no-media | FLAG | false | Omits media folder. |
12 // import
Restores an export bundle into the running instance. Automatically performs SHA-256 checksum verification, creates an automatic safety rollback snapshot, applies database records, and initiates a rebuild.
| Option / Flag | Type | Default | Description |
|---|---|---|---|
| <archive-file> | ARG | required | Path to the .zip or .tar.gz bundle to import. |
| --inspect | FLAG | false | Dry-run mode: prints bundle metadata, version compatibility, and contents without modifying disk. |
| --no-verify | FLAG | false | Bypasses SHA-256 manifest integrity verification. |
| --no-safety-backup | FLAG | false | Skips automatic safety backup generation before overwriting database. |
| --no-build | FLAG | false | Prevents triggering build static compilation after successful restore. |
13 // test-webmention
Diagnostics tool for IndieWeb communication. Tests endpoint discovery on remote URLs, simulates ping transmissions, and validates IndieWebify.me Level 1 representative h-card markup.
| Argument / Option | Type | Description |
|---|---|---|
| <target-url> | ARG | Target URL to discover Webmention endpoint for. |
| --source <url> | PARAM | Source URL on your domain containing the link. |
| --validate-hcard [url] | FLAG | Parses local or remote HTML and asserts presence of p-name, u-url, u-photo, and u-email microformats2. |
14 // version
Displays installed version details, binary compilation status, PHP environment, and build timestamp.
$ php indieinabox.php version
Indie in a Box v1.0.0 (Compiled Standalone Single-File)
Build Date: 2026-09-22 06:59:00 UTC
PHP Version: 8.3.6 (cli) (built: Apr 15 2024 10:20:00)
SQLite Version: 3.45.1 (WAL mode enabled)
15 // update
Integrated in-place self-updater. Communicates with official Codeberg release feeds to verify signatures, download new builds, apply upgrades, and maintain instant rollback backups.
| Option / Flag | Type | Description |
|---|---|---|
| --check | FLAG | Checks Codeberg for available releases without altering files (default behavior). |
| --apply | FLAG | Downloads, verifies checksums, creates a pre-update backup, and replaces indieinabox.php. |
| --backups | FLAG | Lists local historical version backups stored in data/backups/. |
| --rollback [--file <f>] | FLAG | Instantly reverts to the previous binary version. |
$ php indieinabox.php update --check
Current Version: v1.0.0
Latest Available: v1.0.0
[OK] You are running the latest version!
$ php indieinabox.php update --apply
Creating safety backup of indieinabox.php...
Downloading v1.0.0 from Codeberg...
Verifying SHA-256 signature... OK
Applying update in-place...
Running post-update migrations...
[SUCCESS] Updated to Indie in a Box v1.0.0!