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:
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 polyglot dependency management based on go mods and MVS
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 send feedback, bug reports, or any message
Flags:
-h, --help help for hof
-p, --package string the Cue package context to use during execution
-q, --quiet turn off output and assume defaults at prompts
-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:
-p, --package string the Cue package context to use during execution
-q, --quiet turn off output and assume defaults at prompts
-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'
# 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'
# 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
-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:
-p, --package string the Cue package context to use during execution
-q, --quiet turn off output and assume defaults at prompts
-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
-t, --tags strings data tags to inject before run
Global Flags:
-p, --package string the Cue package context to use during execution
-q, --quiet turn off output and assume defaults at prompts
-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 a flexible tool and library based on Go mods.
Use and create module systems with Minimum Version Selection (MVS) semantics
and manage dependencies go mod style. Mix any set of language, code bases,
git repositories, package managers, and subdirectories.
### Features
- Based on go mods MVS system, aiming for 100% reproducible builds.
- Recursive dependencies, version resolution, and code instrospection.
- Custom module systems with custom file names and vendor directories.
- Control configuration for naming, vendoring, and other behaviors.
- Polyglot support for multiple module systems and multiple languages within one tool.
- Works with any git system and supports the main features from go mods.
- Convert other vendor and module systems to MVS or just manage their files with MVS.
- Private repository support for GitHub, GitLab, Bitbucket, and git+SSH.
### Usage
# Print known languages in the current directory
hof mod info
# Initialize this folder as a module
hof mod init <lang> <module-path>
# Add your requirements
vim <lang>.mods # go.mod like file
# Pull in dependencies, no args discovers by *.mods and runs all
hof mod vendor [langs...]
# See all of the commands
hof mod help
### Module File
The module file holds the requirements for project.
It has the same format as a go.mod file.
---
# These are like golang import paths
# i.e. github.com/hofstadter-io/hof
module <module-path>
# Information about the module type / version
# some systems that take this into account
# go = 1.14
<lang> = <version>
# Required dependencies section
require (
# <module-path> <module-semver>
github.com/hof-lang/cuemod--cli-golang v0.0.0 # This is latest on HEAD
github.com/hof-lang/cuemod--cli-golang v0.1.5 # This is a tag v0.1.5 (can omit 'v' in tag, but not here)
)
# replace <module-path> => <module-path|local-path> [version]
replace github.com/hof-lang/cuemod--cli-golang => github.com/hofstadter-io/hofmod-cli-golang v0.2.0
replace github.com/hof-lang/cuemod--cli-golang => ../../cuelibs/cuemod--cli-golang
---
### 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.
If you are using credentials, then private modules can be transparent.
An ENV VAR like GOPRIVATE and CUEPRIVATE can be used to require credentials.
The following ENV VARS are used to set credentials.
GITHUB_TOKEN
GITLAB_TOKEN
BITBUCKET_TOKEN or BITBUCKET_USERNAME / BITBUCKET_PASSWORD *
SSH keys will be looked up in the following ~/.ssh/config, /etc/ssh/config, ~/.ssh/in_rsa
You can configure the SSH key with
HOF_SSHUSR and HOF_SSHKEY
* The bitbucket method will depend on the account type and enterprise license.
### Custom Module Systems
.mvsconfig.cue allows you to define custom module systems.
With some simple configuration, you can create and control
and vendored module system based on go mods.
You can also define global configurations.
See the ./lib/mod/langs in the repository for examples.
### Motivation
- MVS has better semantics for vendoring and gets us closer to 100% reproducible builds.
- JS and Python can have MVS while still using the remainder of the tool chains.
- Prototype for cuelang module and vendor management.
- We need a module system for our [hof-lang](https://hof-lang.org) project.
Usage:
hof mod [command]
Aliases:
mod, m
Available Commands:
info print info about languages and modders known to hof mod
init initialize a new module in the current directory
vendor make a vendored copy of dependencies
Flags:
-h, --help help for mod
Global Flags:
-p, --package string the Cue package context to use during execution
-q, --quiet turn off output and assume defaults at prompts
-v, --verbosity int set the verbosity of output
Use "hof mod [command] --help" for more information about a command.