@solidactions/cli 3.6.0 → 3.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -77,6 +77,52 @@ installed skills and select `solidactions-deploy-and-config` for deployment.
77
77
  For an existing project, install or refresh the same tooling with
78
78
  `solidactions ai init --claude` or `solidactions ai init --agents`.
79
79
 
80
+ ## Database CLI
81
+
82
+ Use the singular `solidactions database` group to manage databases in the
83
+ active workspace. The complete command surface is:
84
+
85
+ ```bash
86
+ solidactions database list --json
87
+ solidactions database create analytics --from backup.sql --json
88
+ solidactions database delete analytics --yes --json
89
+ solidactions database undelete analytics --json
90
+ solidactions database schema analytics --json
91
+ solidactions database query analytics "SELECT * FROM events" --json
92
+ solidactions database exec analytics "DELETE FROM events WHERE expired = 1" --yes --json
93
+ solidactions database dump analytics backup.sql --yes
94
+ solidactions database pull analytics .solidactions/databases/analytics.db --yes
95
+ solidactions database pull analytics --writable
96
+ solidactions database import analytics backup.sql --yes
97
+ solidactions database import analytics backup.sql --resume <checkpoint> --yes
98
+ ```
99
+
100
+ `--json` produces machine-readable output where supported. `delete`, `exec`,
101
+ `dump` overwrites, `pull` overwrites, and `import` prompt before changing data;
102
+ use `--yes` only when that change is already approved. A database `delete` is a
103
+ soft-delete, and its output shows the purge clock during which `undelete` can
104
+ restore it.
105
+
106
+ `query` is read-only SQL; use `exec` for writes. `schema`, `query`, `exec`,
107
+ `pull --writable`, and imports use ephemeral scoped access held only in memory.
108
+ No durable credential or credential sidecar is written locally.
109
+
110
+ By default, `pull` atomically publishes a read-only local replica at
111
+ `.solidactions/databases/<safe-stem>.db`, or at an explicit path. Reuse that
112
+ file for local analytics and transformations. `pull --writable` instead opens a
113
+ foreground session: writes go to the live workspace database.
114
+ No offline merge or background write-back continues after exit.
115
+
116
+ `dump` publishes only a complete SQL file through an owned temporary path and
117
+ refuses unsafe symlink or unapproved overwrite destinations. The CLI rejects
118
+ any import containing `-- DOWNLOAD INCOMPLETE` before making changes. Use
119
+ `create --from <file.sql>` to preflight, create, and load in one flow.
120
+
121
+ Imports commit bounded batches and atomically record a source-bound checkpoint
122
+ under `.solidactions/imports/`. After a partial failure, copy the exact printed
123
+ `--resume <checkpoint>` command to continue without replaying completed
124
+ batches; do not restart the same checkpointed source with a plain import.
125
+
80
126
  ## Configuration
81
127
 
82
128
  The CLI stores `host`, `apiKey`, and `workspaceId` in a JSON config file. Two locations are supported:
@@ -150,6 +196,24 @@ revision after the build. Use `--no-git-metadata` or
150
196
  `SOLIDACTIONS_NO_GIT_METADATA=1` to opt out. Deploying a non-Git directory
151
197
  continues normally without revision metadata.
152
198
 
199
+ ### Env declarations (`solidactions.yaml`)
200
+
201
+ Declare the variables a workflow needs with an `env:` list in `solidactions.yaml`. Each entry uses one of four forms:
202
+
203
+ ```yaml
204
+ env:
205
+ - LOG_LEVEL # plain: declared only, configure with `env set`
206
+ - API_KEY: SHARED_API_KEY # global mapping: defaults to a workspace global variable
207
+ - GCAL_TOKEN:
208
+ oauth: "Google Calendar" # defaults to a workspace OAuth connection
209
+ - ANALYTICS_DB:
210
+ database: "analytics" # defaults to a workspace database
211
+ ```
212
+
213
+ - A global key, an `oauth:` name, and a `database:` name are **mutually exclusive**: bind each variable to exactly one. The platform enforces that server-side (HTTP 422), but do not rely on seeing that error: through CLI v3.6.0 the YAML parser keeps only the first form it recognizes — `oauth:` beats `database:` — so a declaration carrying both deploys silently as the wrong binding instead of failing.
214
+ - `project deploy` (including `--config-only`) syncs the *complete* `env:` list to the server on every run. Any previously YAML-sourced mapping whose name no longer appears in the list is deleted — removing or emptying `env:` prunes those mappings on the next deploy. Only mappings that were never YAML-declared survive: overriding a YAML-declared variable with `env set`/`env map` doesn't change its provenance, so removing its declaration still deletes the mapping.
215
+ - For a `database:` entry, the workflow receives a `DatabaseVar` at `ctx.vars.<NAME>` at runtime, typically wrapped with the SDK's `createDatabaseClient()`. See the SDK reference's [Workspace Databases](https://github.com/SolidActions/solidactions-ts-sdk/blob/main/docs/sdk-reference.md#workspace-databases) section for details.
216
+
153
217
  ## Commands
154
218
 
155
219
  Use `solidactions <command> --help` for full flag details on any command.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schema_version": 1,
3
3
  "cli_name": "solidactions",
4
- "cli_version": "3.6.0",
4
+ "cli_version": "3.7.0",
5
5
  "global_options": [
6
6
  {
7
7
  "flags": "-V, --version",
@@ -364,6 +364,572 @@
364
364
  }
365
365
  ]
366
366
  },
367
+ {
368
+ "path": [
369
+ "database"
370
+ ],
371
+ "name": "database",
372
+ "aliases": [],
373
+ "description": "Manage workspace databases",
374
+ "hidden": false,
375
+ "arguments": [],
376
+ "options": [
377
+ {
378
+ "flags": "-h, --help",
379
+ "long": "--help",
380
+ "short": "-h",
381
+ "description": "display help for command",
382
+ "required": false,
383
+ "value_required": false,
384
+ "value_optional": false,
385
+ "variadic": false,
386
+ "negated": false,
387
+ "hidden": false
388
+ }
389
+ ]
390
+ },
391
+ {
392
+ "path": [
393
+ "database",
394
+ "list"
395
+ ],
396
+ "name": "list",
397
+ "aliases": [],
398
+ "description": "List workspace databases",
399
+ "hidden": false,
400
+ "arguments": [],
401
+ "options": [
402
+ {
403
+ "flags": "--json",
404
+ "long": "--json",
405
+ "short": null,
406
+ "description": "Output as JSON",
407
+ "required": false,
408
+ "value_required": false,
409
+ "value_optional": false,
410
+ "variadic": false,
411
+ "negated": false,
412
+ "hidden": false
413
+ },
414
+ {
415
+ "flags": "-h, --help",
416
+ "long": "--help",
417
+ "short": "-h",
418
+ "description": "display help for command",
419
+ "required": false,
420
+ "value_required": false,
421
+ "value_optional": false,
422
+ "variadic": false,
423
+ "negated": false,
424
+ "hidden": false
425
+ }
426
+ ]
427
+ },
428
+ {
429
+ "path": [
430
+ "database",
431
+ "create"
432
+ ],
433
+ "name": "create",
434
+ "aliases": [],
435
+ "description": "Create a workspace database",
436
+ "hidden": false,
437
+ "arguments": [
438
+ {
439
+ "name": "name",
440
+ "required": true,
441
+ "variadic": false,
442
+ "description": "Database name"
443
+ }
444
+ ],
445
+ "options": [
446
+ {
447
+ "flags": "--from <file.sql>",
448
+ "long": "--from",
449
+ "short": null,
450
+ "description": "Import a SQL file after creation",
451
+ "required": false,
452
+ "value_required": true,
453
+ "value_optional": false,
454
+ "variadic": false,
455
+ "negated": false,
456
+ "hidden": false
457
+ },
458
+ {
459
+ "flags": "--json",
460
+ "long": "--json",
461
+ "short": null,
462
+ "description": "Output as JSON",
463
+ "required": false,
464
+ "value_required": false,
465
+ "value_optional": false,
466
+ "variadic": false,
467
+ "negated": false,
468
+ "hidden": false
469
+ },
470
+ {
471
+ "flags": "-h, --help",
472
+ "long": "--help",
473
+ "short": "-h",
474
+ "description": "display help for command",
475
+ "required": false,
476
+ "value_required": false,
477
+ "value_optional": false,
478
+ "variadic": false,
479
+ "negated": false,
480
+ "hidden": false
481
+ }
482
+ ]
483
+ },
484
+ {
485
+ "path": [
486
+ "database",
487
+ "delete"
488
+ ],
489
+ "name": "delete",
490
+ "aliases": [],
491
+ "description": "Delete a workspace database",
492
+ "hidden": false,
493
+ "arguments": [
494
+ {
495
+ "name": "name",
496
+ "required": true,
497
+ "variadic": false,
498
+ "description": "Database name"
499
+ }
500
+ ],
501
+ "options": [
502
+ {
503
+ "flags": "-y, --yes",
504
+ "long": "--yes",
505
+ "short": "-y",
506
+ "description": "Skip confirmation",
507
+ "required": false,
508
+ "value_required": false,
509
+ "value_optional": false,
510
+ "variadic": false,
511
+ "negated": false,
512
+ "hidden": false
513
+ },
514
+ {
515
+ "flags": "--json",
516
+ "long": "--json",
517
+ "short": null,
518
+ "description": "Output as JSON",
519
+ "required": false,
520
+ "value_required": false,
521
+ "value_optional": false,
522
+ "variadic": false,
523
+ "negated": false,
524
+ "hidden": false
525
+ },
526
+ {
527
+ "flags": "-h, --help",
528
+ "long": "--help",
529
+ "short": "-h",
530
+ "description": "display help for command",
531
+ "required": false,
532
+ "value_required": false,
533
+ "value_optional": false,
534
+ "variadic": false,
535
+ "negated": false,
536
+ "hidden": false
537
+ }
538
+ ]
539
+ },
540
+ {
541
+ "path": [
542
+ "database",
543
+ "undelete"
544
+ ],
545
+ "name": "undelete",
546
+ "aliases": [],
547
+ "description": "Restore a deleted workspace database",
548
+ "hidden": false,
549
+ "arguments": [
550
+ {
551
+ "name": "name",
552
+ "required": true,
553
+ "variadic": false,
554
+ "description": "Database name"
555
+ }
556
+ ],
557
+ "options": [
558
+ {
559
+ "flags": "--json",
560
+ "long": "--json",
561
+ "short": null,
562
+ "description": "Output as JSON",
563
+ "required": false,
564
+ "value_required": false,
565
+ "value_optional": false,
566
+ "variadic": false,
567
+ "negated": false,
568
+ "hidden": false
569
+ },
570
+ {
571
+ "flags": "-h, --help",
572
+ "long": "--help",
573
+ "short": "-h",
574
+ "description": "display help for command",
575
+ "required": false,
576
+ "value_required": false,
577
+ "value_optional": false,
578
+ "variadic": false,
579
+ "negated": false,
580
+ "hidden": false
581
+ }
582
+ ]
583
+ },
584
+ {
585
+ "path": [
586
+ "database",
587
+ "schema"
588
+ ],
589
+ "name": "schema",
590
+ "aliases": [],
591
+ "description": "Show a database schema",
592
+ "hidden": false,
593
+ "arguments": [
594
+ {
595
+ "name": "name",
596
+ "required": true,
597
+ "variadic": false,
598
+ "description": "Database name"
599
+ }
600
+ ],
601
+ "options": [
602
+ {
603
+ "flags": "--json",
604
+ "long": "--json",
605
+ "short": null,
606
+ "description": "Output as JSON",
607
+ "required": false,
608
+ "value_required": false,
609
+ "value_optional": false,
610
+ "variadic": false,
611
+ "negated": false,
612
+ "hidden": false
613
+ },
614
+ {
615
+ "flags": "-h, --help",
616
+ "long": "--help",
617
+ "short": "-h",
618
+ "description": "display help for command",
619
+ "required": false,
620
+ "value_required": false,
621
+ "value_optional": false,
622
+ "variadic": false,
623
+ "negated": false,
624
+ "hidden": false
625
+ }
626
+ ]
627
+ },
628
+ {
629
+ "path": [
630
+ "database",
631
+ "query"
632
+ ],
633
+ "name": "query",
634
+ "aliases": [],
635
+ "description": "Run a read-only SQL query",
636
+ "hidden": false,
637
+ "arguments": [
638
+ {
639
+ "name": "name",
640
+ "required": true,
641
+ "variadic": false,
642
+ "description": "Database name"
643
+ },
644
+ {
645
+ "name": "sql",
646
+ "required": true,
647
+ "variadic": false,
648
+ "description": "SQL query"
649
+ }
650
+ ],
651
+ "options": [
652
+ {
653
+ "flags": "--json",
654
+ "long": "--json",
655
+ "short": null,
656
+ "description": "Output as JSON",
657
+ "required": false,
658
+ "value_required": false,
659
+ "value_optional": false,
660
+ "variadic": false,
661
+ "negated": false,
662
+ "hidden": false
663
+ },
664
+ {
665
+ "flags": "-h, --help",
666
+ "long": "--help",
667
+ "short": "-h",
668
+ "description": "display help for command",
669
+ "required": false,
670
+ "value_required": false,
671
+ "value_optional": false,
672
+ "variadic": false,
673
+ "negated": false,
674
+ "hidden": false
675
+ }
676
+ ]
677
+ },
678
+ {
679
+ "path": [
680
+ "database",
681
+ "exec"
682
+ ],
683
+ "name": "exec",
684
+ "aliases": [],
685
+ "description": "Execute a SQL statement",
686
+ "hidden": false,
687
+ "arguments": [
688
+ {
689
+ "name": "name",
690
+ "required": true,
691
+ "variadic": false,
692
+ "description": "Database name"
693
+ },
694
+ {
695
+ "name": "sql",
696
+ "required": true,
697
+ "variadic": false,
698
+ "description": "SQL statement"
699
+ }
700
+ ],
701
+ "options": [
702
+ {
703
+ "flags": "-y, --yes",
704
+ "long": "--yes",
705
+ "short": "-y",
706
+ "description": "Skip confirmation",
707
+ "required": false,
708
+ "value_required": false,
709
+ "value_optional": false,
710
+ "variadic": false,
711
+ "negated": false,
712
+ "hidden": false
713
+ },
714
+ {
715
+ "flags": "--json",
716
+ "long": "--json",
717
+ "short": null,
718
+ "description": "Output as JSON",
719
+ "required": false,
720
+ "value_required": false,
721
+ "value_optional": false,
722
+ "variadic": false,
723
+ "negated": false,
724
+ "hidden": false
725
+ },
726
+ {
727
+ "flags": "-h, --help",
728
+ "long": "--help",
729
+ "short": "-h",
730
+ "description": "display help for command",
731
+ "required": false,
732
+ "value_required": false,
733
+ "value_optional": false,
734
+ "variadic": false,
735
+ "negated": false,
736
+ "hidden": false
737
+ }
738
+ ]
739
+ },
740
+ {
741
+ "path": [
742
+ "database",
743
+ "dump"
744
+ ],
745
+ "name": "dump",
746
+ "aliases": [],
747
+ "description": "Download a database SQL dump",
748
+ "hidden": false,
749
+ "arguments": [
750
+ {
751
+ "name": "name",
752
+ "required": true,
753
+ "variadic": false,
754
+ "description": "Database name"
755
+ },
756
+ {
757
+ "name": "file",
758
+ "required": false,
759
+ "variadic": false,
760
+ "description": "Destination file"
761
+ }
762
+ ],
763
+ "options": [
764
+ {
765
+ "flags": "-y, --yes",
766
+ "long": "--yes",
767
+ "short": "-y",
768
+ "description": "Overwrite without confirmation",
769
+ "required": false,
770
+ "value_required": false,
771
+ "value_optional": false,
772
+ "variadic": false,
773
+ "negated": false,
774
+ "hidden": false
775
+ },
776
+ {
777
+ "flags": "-h, --help",
778
+ "long": "--help",
779
+ "short": "-h",
780
+ "description": "display help for command",
781
+ "required": false,
782
+ "value_required": false,
783
+ "value_optional": false,
784
+ "variadic": false,
785
+ "negated": false,
786
+ "hidden": false
787
+ }
788
+ ]
789
+ },
790
+ {
791
+ "path": [
792
+ "database",
793
+ "pull"
794
+ ],
795
+ "name": "pull",
796
+ "aliases": [],
797
+ "description": "Pull a database into a local file",
798
+ "hidden": false,
799
+ "arguments": [
800
+ {
801
+ "name": "name",
802
+ "required": true,
803
+ "variadic": false,
804
+ "description": "Database name"
805
+ },
806
+ {
807
+ "name": "path",
808
+ "required": false,
809
+ "variadic": false,
810
+ "description": "Destination path"
811
+ }
812
+ ],
813
+ "options": [
814
+ {
815
+ "flags": "-y, --yes",
816
+ "long": "--yes",
817
+ "short": "-y",
818
+ "description": "Overwrite without confirmation",
819
+ "required": false,
820
+ "value_required": false,
821
+ "value_optional": false,
822
+ "variadic": false,
823
+ "negated": false,
824
+ "hidden": false
825
+ },
826
+ {
827
+ "flags": "--writable",
828
+ "long": "--writable",
829
+ "short": null,
830
+ "description": "Open a foreground writable session",
831
+ "required": false,
832
+ "value_required": false,
833
+ "value_optional": false,
834
+ "variadic": false,
835
+ "negated": false,
836
+ "hidden": false
837
+ },
838
+ {
839
+ "flags": "-h, --help",
840
+ "long": "--help",
841
+ "short": "-h",
842
+ "description": "display help for command",
843
+ "required": false,
844
+ "value_required": false,
845
+ "value_optional": false,
846
+ "variadic": false,
847
+ "negated": false,
848
+ "hidden": false
849
+ }
850
+ ]
851
+ },
852
+ {
853
+ "path": [
854
+ "database",
855
+ "import"
856
+ ],
857
+ "name": "import",
858
+ "aliases": [],
859
+ "description": "Import a SQL file into a database",
860
+ "hidden": false,
861
+ "arguments": [
862
+ {
863
+ "name": "name",
864
+ "required": true,
865
+ "variadic": false,
866
+ "description": "Database name"
867
+ },
868
+ {
869
+ "name": "file.sql",
870
+ "required": true,
871
+ "variadic": false,
872
+ "description": "SQL file"
873
+ }
874
+ ],
875
+ "options": [
876
+ {
877
+ "flags": "-y, --yes",
878
+ "long": "--yes",
879
+ "short": "-y",
880
+ "description": "Skip confirmation",
881
+ "required": false,
882
+ "value_required": false,
883
+ "value_optional": false,
884
+ "variadic": false,
885
+ "negated": false,
886
+ "hidden": false
887
+ },
888
+ {
889
+ "flags": "--resume <checkpoint>",
890
+ "long": "--resume",
891
+ "short": null,
892
+ "description": "Resume from a validated import checkpoint",
893
+ "required": false,
894
+ "value_required": true,
895
+ "value_optional": false,
896
+ "variadic": false,
897
+ "negated": false,
898
+ "hidden": false
899
+ },
900
+ {
901
+ "flags": "-h, --help",
902
+ "long": "--help",
903
+ "short": "-h",
904
+ "description": "display help for command",
905
+ "required": false,
906
+ "value_required": false,
907
+ "value_optional": false,
908
+ "variadic": false,
909
+ "negated": false,
910
+ "hidden": false
911
+ }
912
+ ]
913
+ },
914
+ {
915
+ "path": [
916
+ "database",
917
+ "help"
918
+ ],
919
+ "name": "help",
920
+ "aliases": [],
921
+ "description": "display help for command",
922
+ "hidden": false,
923
+ "arguments": [
924
+ {
925
+ "name": "command",
926
+ "required": false,
927
+ "variadic": false,
928
+ "description": ""
929
+ }
930
+ ],
931
+ "options": []
932
+ },
367
933
  {
368
934
  "path": [
369
935
  "project"