fw new
new
Create a project with its language's own package
Added in 0.1.0.
Creates a Framework project. R projects are created by the framework R package and Python projects by framework-py. fw finds the runtime, runs it, and prints the command to run instead when the runtime is missing. fw builds Stata projects itself: folders, master.do, and settings.do.
Without --from, fw creates an R project from your R defaults (author, directories, and packages), the same as framework::new().
Logged in, fw new NAME --lang stata builds from your defaults on Framework Cloud and saves them for offline use. When the server cannot be reached it uses the saved defaults and says from when. With none saved it asks at a terminal, and without one it stops unless --offline is given. --offline uses the saved defaults, or fw's built-ins, without contacting the server. For Python and R projects fw passes --offline and --workflow to framework-py (0.1.0.dev8 or later) or the framework R package, which apply the same rules. Logged in, they also register the project on Framework Cloud and write FW_PROJECT_TOKEN to its .env. --offline keeps it on this machine.
--from takes a layers file or the slug of one of your projects on Framework Cloud. A project from the cloud gets FW_PROJECT_TOKEN and FW_CLOUD_URL in its .env. --pull-token creates a project from a project token instead of your login; fw asks for the token, or reads it from stdin.
--blueprint, --structure, --package-set, --skill-set, --skill, --tool, --sensitive, --ai, and --git build the project from pieces on Framework Cloud, with your defaults there filling the rest; --defaults uses only your defaults. These need fw login. At a terminal fw then asks whether to also create the project on the cloud, defaulting to No. Without a terminal it creates it there only with --cloud. --no-cloud keeps it on this machine.
--zip has Framework Cloud build the project and downloads it into the folder, so R and Python don't need to be installed. --github OWNER[/REPO] creates the project in a new GitHub repository, private unless --public, waits for it, and clones it here (--no-clone leaves it on GitHub). Both create the project on Framework Cloud and need fw login.
At a terminal, fw new with no name asks for the name, language, and blueprint. Logged in, fw asks how you want the project: built here, downloaded, or on GitHub. --local, --zip, and --github answer that question, and without a terminal fw never asks.
Usage
fw new [NAME] [flags]
Options
| Name | Type | Default | Description |
|---|---|---|---|
| NAME | string |
The project name. With |
|
| --ai | bool |
set up AI assistants and skills; --ai=false turns them off |
|
| --blueprint | string |
start from this blueprint on Framework Cloud, as in fw blueprints list |
|
| --cloud | bool |
also create the project on Framework Cloud, without asking |
|
| --defaults | bool |
build the project from your defaults on Framework Cloud |
|
| --dir | string |
folder to create the project in (default: ./) |
|
| --from | string |
a layers file, or the slug of your project on Framework Cloud |
|
| --git | bool |
create a git repository; --git=false skips it |
|
| --github | string |
create the project on GitHub under OWNER (or OWNER/REPO) and clone it here |
|
| --headless | bool |
run without prompts, for automation; the language package refuses to overwrite existing work |
|
| --lang | string | "r" |
language for a project without --from: r, python, or stata |
| --local | bool |
build the project here with the language's own package, without asking |
|
| --no-clone | bool |
with --github, leave the repository on GitHub without cloning it |
|
| --no-cloud | bool |
create the project only on this machine, without asking |
|
| --no-tool | stringArray | "[]" |
turn off a tool the blueprint or your defaults turn on (repeatable) |
| --offline | bool |
build from your saved Framework Cloud defaults, or the built-ins, without contacting the server |
|
| --package-set | stringArray | "[]" |
add a package set (repeatable) |
| bool |
print the command instead of running it |
||
| --public | bool |
with --github, make the repository public (default: private) |
|
| --pull-token | bool |
create the project from a project token (asked for, or read from stdin) |
|
| --sensitive | bool |
split data and outputs into private and public folders; --sensitive=false turns it off |
|
| --skill | stringArray | "[]" |
add a skill (repeatable) |
| --skill-set | stringArray | "[]" |
add a skill set (repeatable) |
| --structure | string |
use this project structure, as in fw structures list |
|
| --tool | stringArray | "[]" |
turn on a tool, such as quarto or renv (repeatable) |
| --type | string |
project type for a project without --from: project (the Standard Project, the default), project_sensitive, or bare; R and Python also take course and presentation |
|
| --url | string |
Framework Cloud server Environment variable: |
|
| --workflow | string |
how notebooks are written: quarto, jupyter, or scripts (Stata uses scripts) |
|
| --zip | bool |
have Framework Cloud build the project and download it here; needs no R or Python |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Failure |
| 2 | Bad flags or arguments |
| 3 | Not logged in, or the server rejected the token |
| 4 | The server has no such project or resource |
| 5 | Browser login was denied, or its code expired |
| 6 | An upload has "private" in a path; rerun with --include-private if you mean to send it |
With --json, a failure also prints one JSON line on stderr: {"error": "...", "exit_code": 4}. Exit code 6 adds "reason": "private_path".
Examples
Not run
fw new
fw new vaccine-study
fw new survey --lang python --zip
fw new survey --blueprint framework/project --github my-lab/survey
fw new survey --blueprint framework/project --tool renv --sensitive
fw new --from vaccine-study
fw new --from .framework/layers.json --dir . --headless
fw new --pull-token --url https://framework.example.edu