Command Help



hof has several commands typically run during daily development. The first-example will introduce you to these commands and each has a dedicated section for the topic as well.

hof

Top level commands and help message

hof help

$ hof help

hof - the high code framework

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

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

Main commands:
  create                dynamic app blueprints from any git repo
  datamodel             manage, diff, and migrate your data models
  gen                   modular and composable code gen: CUE & data + templates = _
  flow                  run CUE pipelines with the hof/flow DAG engine
  fmt                   format any code and manage the formatters
  mod                   CUE dependency management based on Go mods

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:
  -h, --help             help for hof
      --inject-env       inject all ENV VARs as default tag vars
  -p, --package string   the Cue package context to use during execution
  -q, --quiet            turn off output and assume defaults at prompts
  -t, --tags strings     @tags() to be injected into CUE code
  -v, --verbosity int    set the verbosity of output

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

hof / datamodel

Used for data model management (dm for short)

See the Data Modeling section for details.

hof help datamodel

$ hof help datamodel

Data models are sets of models which are used in many hof processes and modules.

At their core, they represent the most abstract representation for objects and
their relations in your applications. They are extended and annotated to add
context fot their usage in different code generators: (DB vs Server vs Client).

Beyond representing models in their current form, a history is maintained so that:
  - database migrations can be created and managed
  - servers can handle multiple model versions
  - clients can implement feature flags
Much of this is actually handled by code generators and must be implemented there.
Hof handles the core data model definitions, history, and snapshot creation.

Usage:
  hof datamodel [command]

Aliases:
  datamodel, dm

Available Commands:
  checkpoint  create a snapshot of the data model
  diff        show the diff between data model version
  history     list the snapshots for a data model
  info        print details for a data model
  list        print available data models
  log         show the history of diffs for a data model

Flags:
  -d, --datamodel strings   Datamodels for the datamodel commands
  -f, --format string       Pick format from Cuetils (default "_")
  -h, --help                help for datamodel
  -m, --model strings       Models for the datamodel commands
  -o, --output string       Output format [table,cue] (default "table")
  -s, --since string        Timestamp to filter since
  -u, --until string        Timestamp to filter until

Global Flags:
      --inject-env       inject all ENV VARs as default tag vars
  -p, --package string   the Cue package context to use during execution
  -q, --quiet            turn off output and assume defaults at prompts
  -t, --tags strings     @tags() to be injected into CUE code
  -v, --verbosity int    set the verbosity of output

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

hof / gen

Create one-liners to generate files with data, CUE, and templates or use composable generators to build out advanced applications.

See the code gen docs to learn more

hof help flow

$ hof help gen

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

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

Aliases:
  gen, G

Flags:
      --as-module string      <github.com/username/<name>> like value for the generator module made from the given flags
  -D, --diff3                 enable diff3 support for custom code
  -G, --generator strings     generator tags to run, default is all, or none if -T is used
  -h, --help                  help for gen
      --init string           <name> to bootstrap a new genarator module
  -l, --list                  list available generators
      --no-format             disable formatting during code gen (ad-hoc only)
  -O, --outdir string         base directory to write all output u
  -P, --partial strings       file globs to partial templates to register with the templates
  -s, --stats                 print generator statistics
  -T, --template strings      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 strings    filepath globs to watch for changes and trigger fast regen
  -W, --watch-globs strings   filepath globs to watch for changes and trigger full regen

Global Flags:
      --inject-env       inject all ENV VARs as default tag vars
  -p, --package string   the Cue package context to use during execution
  -q, --quiet            turn off output and assume defaults at prompts
  -t, --tags strings     @tags() to be injected into CUE code
  -v, --verbosity int    set the verbosity of output

hof / flow

Build workflows and scripts with CUE and a DAG engine

See the flow docs to learn more

hof help flow

$ hof help flow

run CUE pipelines with the hof/flow DAG engine

Use hof/flow to transform data, call APIs, work with DBs,
read and write files, call any program, handle events,
and much more.

'hof flow' is very similar to 'cue cmd' and built on the same flow engine.
Tasks and dependencies are inferred.
Hof flow has a slightly different interface and more task types.

Docs: https://docs.hofstadter.io/data-flow

Example:

  @flow()

  call: {
    @task(api.Call)
    req: { ... }
    resp: {
      statusCode: 200
      body: string
    }
  }

  print: {
    @task(os.Stdout)
    test: call.resp
  }

Arguments:
  cue entrypoints are the same as the cue cli
  @path/name  is shorthand for -f / --flow should match the @flow(path/name)
  +key=value  is shorthand for -t / --tags and are the same as CUE injection tags

  arguments can be in any order and mixed

@flow() indicates a flow entrypoint
  you can have many in a file or nested values
  you can run one or many with the -f flag

@task() represents a unit of work in the flow dag
  intertask dependencies are autodetected and run appropriately
  hof/flow provides many built in task types
  you can reuse, combine, and share as CUE modules, packages, and values

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

Aliases:
  flow, f

Flags:
  -d, --docs           print pipeline docs
  -f, --flow strings   flow labels to match and run
  -h, --help           help for flow
  -l, --list           list available pipelines
      --progress       print task progress as it happens
  -s, --stats          Print final task statistics

Global Flags:
      --inject-env       inject all ENV VARs as default tag vars
  -p, --package string   the Cue package context to use during execution
  -q, --quiet            turn off output and assume defaults at prompts
  -t, --tags strings     @tags() to be injected into CUE code
  -v, --verbosity int    set the verbosity of output

hof / mod

Manage a MVS (Golang) style modules and dependencies. Create custom module systems with a single config file.

Also, more typically, used as a stop gap for CUE modules until cue mod is implemented.

typical usage

# initialize a new module
hof mod init cue hof.io/docs/example

# download dependencies
hof mod vendor cue
hof help mod

$ hof help mod

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
  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:
      --inject-env       inject all ENV VARs as default tag vars
  -p, --package string   the Cue package context to use during execution
  -q, --quiet            turn off output and assume defaults at prompts
  -t, --tags strings     @tags() to be injected into CUE code
  -v, --verbosity int    set the verbosity of output

Use "hof mod [command] --help" for more information about a command.
2023 Hofstadter, Inc