Command Help

hof - the higher order framework

  Learn more at https://docs.hofstadter.io

Usage:
  hof [flags] [command] [args]

Main commands:
  chat                  co-create with AI (alpha)
  create                starter kits or blueprints from any git repo
  datamodel             manage, diff, and migrate your data models
  def                   print consolidated CUE definitions
  eval                  evaluate and print CUE configuration
  export                output data in a standard format
  flow                  run workflows and tasks powered by CUE
  fmt                   format any code and manage the formatters
  gen                   CUE powered code generation
  mod                   CUE module dependency management
  tui                   a terminal interface to Hof and CUE
  vet                   validate data with CUE

Additional commands:
  help                  help about any command
  update                check for new versions and run self-updates
  version               print detailed version information
  completion            generate completion helpers for your terminal
  feedback              open an issue or discussion on GitHub

Flags:
  -E, --all-errors           print all available errors
  -h, --help                 help for hof
  -i, --ignore-errors        turn off output and assume defaults at prompts
  -D, --include-data         auto include all data files found with cue files
  -V, --inject-env           inject all ENV VARs as default tag vars
  -I, --input stringArray    extra data to unify into the root value
  -p, --package string       the Cue package context to use during execution
  -l, --path stringArray     CUE expression for single path component when placing data files
  -q, --quiet                turn off output and assume defaults at prompts
  -d, --schema stringArray   expression to select schema to apply to data files
      --stats                print generator statistics
  -0, --stdin-empty          A flag that ensure stdin is zero and does not block
  -t, --tags stringArray     @tags() to be injected into CUE code
  -v, --verbosity int        set the verbosity of output
      --with-context         add extra context for data files, usable in the -l/path flag

Use "hof [command] --help / -h" for more information about a command.

Data models are values or objects used in many hof processes and modules.
The "datamodel" command helps you manage them and track their change history.
At their core, they represent the models that make up your application.
The intention is to define a data model for your entire application once,
then use this source of truth to generate code from database to server to client.

Hof's schema for datamodels is minimal and flexible, allowing you to define the
shape based on your application. You can have multiple datamodels as well.
You can also control and where and how history should be tracked. This history
is included during code generation so that database migrations and functions
for converting between versions can be created.

# Examples Datamodels

-- config.cue --
package datamodel

import (
	"github.com/hofstadter-io/hof/schema/dm"
	"github.com/hofstadter-io/hof/schema/dm/fields"
)

// Track an entire oject
Config: dm.Object & {

	host: fields.String & { Default: "8080" }

	database: {
		host:   fields.String
		port:   fields.String
		dbconn: fields.String
	}
}

-- database.cue --
package datamodel

import (
	"github.com/hofstadter-io/hof/schema/dm/sql"
	"github.com/hofstadter-io/hof/schema/dm/fields"
)

// Traditional database model which maps onto tables & columns
Datamodel: sql.Datamodel & {
	// implied through definition, duplicated here for example clarity
	$hof: metadata: {
		id:   "datamodel-abc123"
		name: "MyDatamodel"
	}

	Models: {
		User: {
			Fields: {
				ID:        fields.UUID
				CreatedAt: fields.Datetime
				UpdatedAt: fields.Datetime
				DeletedAt: fields.Datetime

				email:    fields.Email
				username: fields.String
				password: fields.Password
				verified: fields.Bool
				active:   fields.Bool

				persona: fields.Enum & {
					Vals: ["guest", "user", "admin", "owner"]
					Default: "user"
				}
			}
		}
	}
}

# Example Usage   (dm is short for datamodel)

  $ hof dm list   (print known data models)
  NAME         TYPE       VERSION  STATUS  ID
  Config       object     -        ok      Config
  MyDatamodel  datamodel  -        ok      datamodel-abc123

  $ hof dm tree   (print the structure of the datamodels)

  $ hof dm diff   (prints a tree based diff of the datamodel)

  $ hof dm checkpoint -m "a message about this checkpoint"

  $ hof dm log    (prints the log of changes from latest to oldest)

  You can also use the -d & -e flags to subselect datamodels and nested values

# Learn more:
  - https://docs.hofstadter.io/getting-started/data-layer/
  - https://docs.hofstadter.io/data-modeling/

Usage:
  hof datamodel [command]

Aliases:
  datamodel, dm

Available Commands:
  checkpoint  create a snapshot of the data model
  diff        show the current diff or between datamodel versions
  list        print available datamodels
  log         show the history for a datamodel
  tree        print datamodel structure as a tree

Flags:
  -e, --expr stringArray    CUE paths to select outputs, depending on the command
  -h, --help                help for datamodel
  -M, --model stringArray   specify one or more data models to operate on

Global Flags:
  -E, --all-errors           print all available errors
  -i, --ignore-errors        turn off output and assume defaults at prompts
  -D, --include-data         auto include all data files found with cue files
  -V, --inject-env           inject all ENV VARs as default tag vars
  -I, --input stringArray    extra data to unify into the root value
  -p, --package string       the Cue package context to use during execution
  -l, --path stringArray     CUE expression for single path component when placing data files
  -q, --quiet                turn off output and assume defaults at prompts
  -d, --schema stringArray   expression to select schema to apply to data files
      --stats                print generator statistics
  -0, --stdin-empty          A flag that ensure stdin is zero and does not block
  -t, --tags stringArray     @tags() to be injected into CUE code
  -v, --verbosity int        set the verbosity of output
      --with-context         add extra context for data files, usable in the -l/path flag

Use "hof datamodel [command] --help" for more information about a command.

hof unifies CUE with Go's text/template system and diff3
  create on-liners to generate any file from any 
  build reusable and modular generators
  edit and regenerate those files while keeping changes

# Render a template
  hof gen input.cue -T template.txt
  hof gen input.yaml schema.cue -T template.txt > output.txt

# Add partials to the template context
  hof gen input.cue -T template.txt -P partial.txt

# The template flag as code gen mappings
  hof gen input.cue -T ... -T ...

  # Generate multiple templates at once
  -T templateA.txt -T templateB.txt

  # Select a sub-input value by CUEpath
  -T templateA.txt:foo
  -T templateB.txt:sub.val

  # Choose a schema with @
  -T templateA.txt:foo@Foo
  -T templateB.txt:sub.val@schemas.val

  # Writing to file with = (semicolon)
  -T templateA.txt=a.txt
  -T templateB.txt:sub.val@schema=b.txt

  # Templated output path, braces need quotes
  -T templateA.txt:='{{ .name | lower }}.txt'

	# Data Files are created when no template
  -T :sub.val='{{ .name | lower }}.json'

  # Repeated templates are used when
  # 1. the output has a '[]' prefix
  # 2. the input is a list or array
  #   The template will be processed per entry
  #   This also requires using a templated outpath
  -T template.txt:items='[]out/{{ .filepath }}.txt'
  -T :items='[]out/{{ .filepath }}.yaml'

  # Output everything to a directory (out name is the same)
  -O out -T types.go -T handlers.go

  # Watch files and directories, doing full or Xcue-less reloads
  -W *.cue -X *.go -O out -T types.go -T handlers.go

# Turn any hof gen flags into a reusable generator module
  hof gen [entrypoints] flags... --as-module [name]
  hof gen [entrypoints] -G [name]

# Bootstrap a new generator module
  hof gen init github.com/hofstadter-io/demos

# List availabel generators
	hof gen list

# Learn about writing templates, with extra functions and helpers
  https://docs.hofstadter.io/code-generation/template-writing/

# Check the tests for complete examples
  https://github.com/hofstadter-io/hof/tree/_dev/test/render

# Compose code gen mappings into reusable modules with
  hof gen app.cue -G frontend -G backend -G migrations -T ...
  https://docs.hofstadter.io/first-example/

Usage:
  hof gen [files...] [flags]
  hof gen [command]

Aliases:
  gen, G

Available Commands:
  info        print details for about generators
  init        initialize a new generator
  list        print available generators

Flags:
      --as-module string          <github.com/username/<name>> like value for the generator module made from the given flags
  -3, --diff3                     enable diff3 support for custom code
      --exec                      enable pre/post-exec support when generating code
  -G, --generator stringArray     generator tags to run, default is all, or none if -T is used
  -h, --help                      help for gen
      --keep-deleted              keep files that would be deleted after code generation
      --no-format                 disable formatting during code gen (ad-hoc only)
  -O, --outdir string             base directory to write all output u
  -P, --partial stringArray       file globs to partial templates to register with the templates
  -T, --template stringArray      template mapping to render, see help for format
  -w, --watch                     run in watch mode, regenerating when files change, implied by -W/X
  -X, --watch-fast stringArray    filepath globs to watch for changes and trigger fast regen
  -W, --watch-globs stringArray   filepath globs to watch for changes and trigger full regen

Global Flags:
  -E, --all-errors           print all available errors
  -i, --ignore-errors        turn off output and assume defaults at prompts
  -D, --include-data         auto include all data files found with cue files
  -V, --inject-env           inject all ENV VARs as default tag vars
  -I, --input stringArray    extra data to unify into the root value
  -p, --package string       the Cue package context to use during execution
  -l, --path stringArray     CUE expression for single path component when placing data files
  -q, --quiet                turn off output and assume defaults at prompts
  -d, --schema stringArray   expression to select schema to apply to data files
      --stats                print generator statistics
  -0, --stdin-empty          A flag that ensure stdin is zero and does not block
  -t, --tags stringArray     @tags() to be injected into CUE code
  -v, --verbosity int        set the verbosity of output
      --with-context         add extra context for data files, usable in the -l/path flag

Use "hof gen [command] --help" for more information about a command.

run workflows and tasks powered by CUE

Usage:
  hof flow [cue files...] [@flow/name...] [+key=value] [flags]
  hof flow [command]

Aliases:
  flow, f

Available Commands:
  list        print available flows

Flags:
  -B, --bulk string        exprs for inputs to run workflow in bulk mode
  -F, --flow stringArray   flow labels to match and run
  -h, --help               help for flow
  -P, --parallel int       global flow parallelism (default 1)
      --progress           print task progress as it happens

Global Flags:
  -E, --all-errors           print all available errors
  -i, --ignore-errors        turn off output and assume defaults at prompts
  -D, --include-data         auto include all data files found with cue files
  -V, --inject-env           inject all ENV VARs as default tag vars
  -I, --input stringArray    extra data to unify into the root value
  -p, --package string       the Cue package context to use during execution
  -l, --path stringArray     CUE expression for single path component when placing data files
  -q, --quiet                turn off output and assume defaults at prompts
  -d, --schema stringArray   expression to select schema to apply to data files
      --stats                print generator statistics
  -0, --stdin-empty          A flag that ensure stdin is zero and does not block
  -t, --tags stringArray     @tags() to be injected into CUE code
  -v, --verbosity int        set the verbosity of output
      --with-context         add extra context for data files, usable in the -l/path flag

Use "hof flow [command] --help" for more information about a command.

hof mod is CUE dependency management based on Go mods.

### Module File

The module file holds the requirements for project.
It is found in cue.mod/module.cue	

---
// These are like golang import paths
//   i.e. github.com/hofstadter-io/hof
module: "<module-path>"
cue: "v0.5.0"

// Required dependencies section
require: {
  // "<module-path>": "<module-semver>"
  "github.com/hofstadter-io/ghacue": "v0.2.0"
  "github.com/hofstadter-io/hofmod-cli": "v0.8.1"
}

// Indirect dependencies (managed by hof)
indirect: { ... }

// Replace dependencies with local or remote
replace: {
  "github.com/hofstadter-io/ghacue": "github.com/myorg/ghacue": "v0.4.2"
  "github.com/hofstadter-io/hofmod-cli": "../mods/clie"
}
---


### Authentication and private modules

hof mod prefers authenticated requests when fetching dependencies.
This increase rate limits with hosts and supports private modules.
Both token and sshkey base methods are supported, with preferences:

1. Matching entry in .netrc
  machine github.com
  login github-token
  password <github-token-value>

2. ENV VARS for well known hosts.

  GITHUB_TOKEN
  GITLAB_TOKEN
  BITBUCKET_USERNAME / BITBUCKET_PASSWORD or BITBUCKET_TOKEN 

  The bitbucket method will depend on the account type and enterprise license.

3. SSH keys 

  the following are searched: ~/.ssh/config, /etc/ssh/config, ~/.ssh/id_rsa


### Usage

there are two main commands you will use, init & tidy

# Initialize the current folder as a module
hof mod init <module-path>     (like github.com/org/repo)

# Refresh dependencies, discovering any new imports
hof mod tidy

# Add a dependency
hof mod get github.com/hofstadter-io/hof@v0.6.8
hof mod get github.com/hofstadter-io/hof@v0.6.8-beta.6
hof mod get github.com/hofstadter-io/hof@latest   // latest semver
hof mod get github.com/hofstadter-io/hof@next     // next prerelease
hof mod get github.com/hofstadter-io/hof@main     // latest commit on branch

# Update dependencies
hof mod get github.com/hofstadter-io/hof@latest
hof mod get all@latest

# Symlink dependencies from local cache
hof mod link

# Copy dependency code from local cache
hof mod vendor

# Verify dependency code against cue.mod/sums.cue
hof mod verify

# This helpful output
hof mod help

Usage:
  hof mod [command]

Aliases:
  mod, m

Available Commands:
  clean       clean hof's module cache
  get         add a new dependency to the current module
  init        initialize a new module in the current directory
  link        symlink dependencies to cue.mod/pkg
  publish     publish a module
  tidy        recalculate dependencies and update mod files
  vendor      copy dependencies to cue.mod/pkg
  verify      verify integrity of dependencies

Flags:
  -h, --help   help for mod

Global Flags:
  -E, --all-errors           print all available errors
  -i, --ignore-errors        turn off output and assume defaults at prompts
  -D, --include-data         auto include all data files found with cue files
  -V, --inject-env           inject all ENV VARs as default tag vars
  -I, --input stringArray    extra data to unify into the root value
  -p, --package string       the Cue package context to use during execution
  -l, --path stringArray     CUE expression for single path component when placing data files
  -q, --quiet                turn off output and assume defaults at prompts
  -d, --schema stringArray   expression to select schema to apply to data files
      --stats                print generator statistics
  -0, --stdin-empty          A flag that ensure stdin is zero and does not block
  -t, --tags stringArray     @tags() to be injected into CUE code
  -v, --verbosity int        set the verbosity of output
      --with-context         add extra context for data files, usable in the -l/path flag

Use "hof mod [command] --help" for more information about a command.